Nombre
Obtener un país
Datos de un país por su código ISO 3166-1 alpha-2.
Método HTTP y ruta
/https:
Qué pasa al ejecutarlo
- Solo consulta: no cambia datos de tu organización.
- La llamada no se cobra.
Qué hace
Devuelve los datos de un país por su código ISO 3166-1 alpha-2 (2 letras, sin distinguir mayúsculas).
Disponibilidad y requisitos previos
- Publicado y disponible en la API v6 de producción.
- Todas las rutas parten de
https:./ / developers. hablame. co - Necesitas una API key de Hablame para llamarlo.
Autenticación y permisos
- Envía tu API key en la cabecera
Authorizationcon el esquema Bearer.
Quién puede llamarlo: Cualquier API key válida.
Límites y consideraciones operativas
Límite de uso: 60 solicitudes por minuto.
Parámetros de ruta
| Nombre | Tipo | Descripción y reglas |
|---|---|---|
codeObligatorio | string | Código ISO 3166-1 alpha-2 del país ( Largo mínimo: |
Parámetros de consulta
| Nombre | Tipo | Descripción y reglas |
|---|---|---|
langOpcional | string | Código ISO-639-1. Devuelve Valores permitidos: |
Encabezados HTTP
| Nombre | Tipo | Descripción y reglas |
|---|---|---|
AuthorizationObligatorio | string | Tu API key con el esquema Bearer. Ejemplo: |
Cuerpo de la petición
Este endpoint no recibe cuerpo en la petición.
Respuestas satisfactorias
200
Datos del país.
{
"success": true,
"data": {
"code": "CO",
"code3": "COL",
"callingCode": "57",
"mcc": "732",
"flag": "https://flagcdn.com/co.svg",
"name": "Colombia"
},
"meta": {
"requestId": "b9b1704baffab211",
"clientIp": "203.0.113.45",
"timestamp": "2026-05-23T02:00:00+00:00",
"responseTimeMs": 2.1
}
}Los valores del ejemplo son ilustrativos.
Campos de la respuesta
| Nombre | Tipo | Descripción y reglas |
|---|---|---|
successSiempre presente | boolean | |
dataSiempre presente | object | |
data.Siempre presente | string | ISO 3166-1 alpha-2 (2 letras MAYÚSCULA). Ejemplo: |
data.Siempre presente | string | ISO 3166-1 alpha-3. Ejemplo: |
data.Siempre presente | string | Indicativo E.164, sin Ejemplo: |
data.Siempre presente | string | Mobile Country Code (E.212). Ejemplo: |
data.Siempre presente | string | URL de la bandera (SVG). Formato: |
data. | object | Nombre del país por idioma ( |
data. | string | |
data. | string | Nombre del país en el |
metaSiempre presente | object | Metadatos de la respuesta. |
meta.Siempre presente | string | Identificador único de la solicitud (16 caracteres hexadecimales). Es el mismo de la cabecera Ejemplo: |
meta.Siempre presente | string | IP con la que la API vio tu solicitud. Útil si tu API key solo admite ciertas redes. Ejemplo: |
meta.Siempre presente | string | Fecha y hora en que se construyó la respuesta (ISO 8601 con offset). Formato: |
meta.Siempre presente | number | Tiempo (ms) que tomó procesar la solicitud en el servidor. Ejemplo: |
Códigos de error
Todas las respuestas de error tienen la misma forma: success en false y un objeto error cuyo code dice qué pasó. Aquí están agrupadas por tipo, con los códigos que este endpoint puede devolver.
Forma de una respuesta de error
| Nombre | Tipo | Descripción y reglas |
|---|---|---|
successSiempre presente | boolean | Valor fijo: |
metaSiempre presente | object | Metadatos de la respuesta. |
meta.Siempre presente | string | Identificador único de la solicitud (16 caracteres hexadecimales). Es el mismo de la cabecera Ejemplo: |
meta.Siempre presente | string | IP con la que la API vio tu solicitud. Útil si tu API key solo admite ciertas redes. Ejemplo: |
meta.Siempre presente | string | Fecha y hora en que se construyó la respuesta (ISO 8601 con offset). Formato: |
meta.Siempre presente | number | Tiempo (ms) que tomó procesar la solicitud en el servidor. Ejemplo: |
errorSiempre presente | object | |
error.Siempre presente | string | Identificador estable en UPPER_SNAKE_CASE. Los clientes ramifican sobre este valor. Ejemplo: |
error. | integer | Código numérico legacy v5, solo cuando hay puente. Se omite en los códigos nacidos en v6. Ejemplo: |
error.Siempre presente | string | URL a la documentación del error. Formato: |
error.Siempre presente | string | Texto legible en inglés. Es para el log del desarrollador, no para el usuario final: no lo parsees. |
error.Siempre presente | array<object> | Contexto estructurado (validaciones, recurso afectado). Arreglo vacío cuando no hay contexto extra. |
Validación
Este endpoint no declara respuestas de este tipo.
Autenticación
- 401Credenciales inválidas o faltantes.
No se envió un token Bearer y cada llamada lo requiere.
Mensaje que devuelve la API: Authentication is required. Send your API key as `Authorization: Bearer <token>`.
La clave de API no se reconoce: formato equivocado, revocada o vencida.
Mensaje que devuelve la API: The provided API key is invalid or has expired. Please verify the value sent in the `Authorization: Bearer` header.
Permisos
La clave solo funciona desde ciertas redes y tu IP no está entre ellas.
Mensaje que devuelve la API: This API key cannot be used from this IP address. The address we saw is in `meta.clientIp`: call from one of the networks allowed for the key, or use a key that allows this one.
Tu organización está suspendida o cerrada.
Mensaje que devuelve la API: The organization associated with this API key is not active. Please contact support.
Límites de uso
- 429Se excedió el límite de solicitudes.
Excediste el cupo de tu organización para este endpoint.
Mensaje que devuelve la API: You have exceeded the allowed request rate for this endpoint. Please wait before retrying.
Volumen inusualmente alto desde tu IP de origen.
Mensaje que devuelve la API: Too many requests from this IP within a short window. Please wait before retrying.
Recurso inexistente
- 404No existe un país con ese código.
No existe un país con ese código.
Mensaje que devuelve la API: No country was found with the supplied code. Use the ISO 3166-1 alpha-2 form (e.g. `CO`, `US`).
Errores internos y disponibilidad
503 genérico: un servicio del que dependemos no responde.
Otras respuestas
Este endpoint no declara respuestas de este tipo.
Consideraciones especiales
Este endpoint no tiene consideraciones especiales.