Códigos de error de la API
Cada código de error de la API Outbound con su estado HTTP, su significado y su solución, para que tu integración reaccione correctamente.
Si la API Outbound rechaza una solicitud, responde con success: false, un código fijo en error y una explicación en message. Tu integración decide según error, no según el texto: los códigos se mantienen estables, los textos pueden cambiar.
{
"success": false,
"error": "invalid_to_number",
"message": "toNumber must be an international number in E.164 format …"
}
Resumen
| Estado | Significado | ¿Reintentar? |
|---|---|---|
| 400 | La solicitud está incompleta o no es válida | solo después de corregirla |
| 401 | Falta la autenticación o no es válida | solo después de corregirla |
| 402 | Falta la suscripción o el pago para esta vía | solo después del pago |
| 403 | Esta acción aún no está habilitada para tu cuenta o el número | solo después de habilitarla |
| 409 | Una solicitud con el mismo Idempotency-Key sigue en curso | sí, después de Retry-After |
| 422 | La solicitud no encaja con la configuración | solo después de corregirla |
| 429 | Límite alcanzado | sí, después de Retry-After |
| 500, 503 | Error por nuestra parte | sí, tras una pausa y con el mismo Idempotency-Key |
400: solicitud no válida
invalid_to_number
El número de destino no está en formato E.164. Escríbelo con signo más y prefijo del país, por ejemplo +491701234567. La API rechaza formatos nacionales como 0170 …, porque de ellos no se deduce el país con seguridad.
invalid_from_number
El número de origen no está en formato E.164. Escríbelo como el número de destino, con signo más y prefijo del país.
outbound_number_required
Falta fromNumber. Indica tu número de origen: un número importado o conectado por SIP que tenga un agente asignado.
platform_number_inbound_only
El número de origen es un número comprado en bhomy. Estos números solo reciben llamadas. Importa tu propio número o conéctalo por SIP.
invalid_idempotency_key
El header Idempotency-Key está vacío, tiene más de 255 caracteres o contiene caracteres fuera de ASCII. Usa, por ejemplo, un UUID.
validation_error
No se ha podido comprobar el número de origen en este momento. Vuelve a intentarlo tras una pausa.
Si falta el body o no es un JSON válido, la API también responde con 400, en ese caso con una explicación en error, por ejemplo «Missing required field: toNumber».
401: autenticación
Con 401, el motivo está en code:
code | Solución |
|---|---|
auth.missing_header | Envía el header Authorization: Bearer … |
auth.invalid_type | El header empieza por Bearer seguido de un espacio |
auth.invalid_key | La clave no existe. Comprueba que no tenga espacios ni saltos de línea |
auth.key_revoked | La clave está desactivada. Reactívala en Clave API o usa otra |
Más información en Problemas con claves API.
402: pago
imported_number_subscription
Las llamadas desde un número importado requieren una suscripción activa sin facturas pendientes. Paga las facturas pendientes en Facturación.
403: aún no habilitado
identity_not_verified
A través de la API, bhomy solo llama cuando tu identidad está verificada. La respuesta contiene verify_url, el enlace a la tarjeta Identidad en Facturación. La verificación la haces una sola vez, consulta Llamadas salientes.
sender_not_verified
El número de origen aún no está confirmado para llamadas salientes. Confírmalo con la llamada de verificación en su configuración, en Número de teléfono.
outbound_disabled
Las llamadas salientes no están configuradas para este número SIP. Conéctalo con la dirección de terminación y las credenciales de tu proveedor.
409: sigue en curso
idempotency_request_in_progress
Se está procesando una solicitud con el mismo Idempotency-Key. Espera los segundos indicados en Retry-After y envía de nuevo la misma solicitud. Recibirás entonces la respuesta de la primera.
422: no encaja con la configuración
idempotency_key_reused
Este Idempotency-Key ya pertenece a otra solicitud. Usa una clave nueva para cada llamada nueva.
no_assistant_mapped
El número de origen no tiene ningún agente asignado. Asígnale un agente en Número de teléfono.
imported_number_destination
Un número importado llama a números fijos y móviles alemanes. Para otros destinos, usa un número SIP a través de tu propio proveedor.
429: límite alcanzado
rate_limit_exceeded
Más de 60 solicitudes en 60 segundos. limit_scope indica el límite: por dirección IP o por clave API. Espera los segundos indicados en Retry-After y reparte tus solicitudes.
concurrent_limit_reached
Todas las líneas están ocupadas. Con limit_scope: "account", se trata de las llamadas simultáneas de tu plan, y la respuesta indica entonces current y limit. Con limit_scope: "platform", bhomy reserva brevemente líneas para llamadas entrantes. En ambos casos, espera los segundos indicados en Retry-After.
500 y 503: error por nuestra parte
outbound_not_configured
Las llamadas salientes no están configuradas por nuestra parte en este momento. Ponte en contacto con el soporte.
outbound_unavailable
El servicio de llamadas salientes no está disponible temporalmente. Vuelve a intentarlo en unos minutos.
dispatch_failed
No se ha podido poner en marcha al agente. Vuelve a intentarlo con el mismo Idempotency-Key, así no se produce ninguna llamada duplicada.
internal_error
Un error inesperado. Vuelve a intentarlo. Si el error persiste, escríbenos.
En estos errores, la respuesta suele contener error_id. Envíanoslo, consulta Informar de un problema. Así encontramos el proceso de inmediato.
Si se aceptó el encargo pero no hubo conversación
Una respuesta 202 significa que el encargo se ha aceptado. Lo que ocurre después aparece como resultado de la llamada en el historial de llamadas, por ejemplo Sin respuesta, Buzón de voz o Bloqueada si tu cuenta estaba bloqueada. Los resultados se explican en Campañas.
¿Te ha sido útil esta página?