Códigos de Error

En caso de error revisa el código HTTP y el campo message.

Cuerpo de error

Los errores de negocio siempre devuelven un code legible por máquina para que pueda ramificar programáticamente. Los parámetros inválidos (validación) y las rutas desconocidas devuelven el formato estándar de Laravel: { “message”: ”…”, “errors”: { … } }. Valide las entradas antes de enviarlas.

{
  "code": "insufficient_balance",
  "message": "Insufficient balance. Please top up and try again."
}

Error

code	HTTP	Descripción
unauthorized	401	Falta la clave de API, no es válida o está inactiva.
account_banned	403	Cuenta suspendida. Contacte con soporte.
invalid_realtime_request	400	Solicitud en tiempo real malformada (p. ej., número sin prefijo internacional + cuando se omite country).
idempotency_key_required	400	Las solicitudes en tiempo real requieren el encabezado Idempotency-Key.
invalid_idempotency_key	422	Idempotency-Key inválido: 1-128 caracteres de letras, dígitos y . _ : -
idempotency_conflict	409	La misma Idempotency-Key se usó con un contenido de solicitud diferente.
request_in_progress	409	Una solicitud en tiempo real idéntica sigue procesándose. Reintente en breve (Retry-After: 1).
empty_input	422	El archivo subido no contiene filas utilizables.
product_not_found	422	El slug de producto enviado no existe o está inactivo.
product_mode_not_supported	422	Este endpoint no acepta este modo de producto (los productos en tiempo real no van a endpoints masivos).
invalid_country	422	El producto no admite el país enviado.
too_few_numbers	422	El envío está por debajo del mínimo del producto.
too_many_numbers	422	El envío supera el máximo de la plataforma.
insufficient_balance	402	Saldo insuficiente. Recargue y reintente.
realtime_disabled	403	La detección en tiempo real no está habilitada para esta cuenta.
realtime_rate_limited	429	Límite de solicitudes en tiempo real superado. Respete retry_after.
product_pricing_unavailable	503	El precio de este producto aún no está configurado. Contacte con soporte.
detection_capacity_unavailable	503	No hay capacidad de detección disponible ahora mismo. Reintente más tarde.
realtime_route_unavailable	503	No hay ruta en tiempo real disponible. Reintente más tarde.
realtime_fact_cache_unavailable	503	Una dependencia en tiempo real no está disponible temporalmente. Reintente más tarde.
realtime_rate_limiter_unavailable	503	El limitador de solicitudes no está disponible temporalmente. Reintente más tarde.
internal_error	500	Error interno del servidor. Es seguro reintentar con la misma Idempotency-Key.

Fallos sin código

No todos los fallos tienen un code. Los endpoints de tarea informan de cuatro condiciones solo con el estado HTTP y message, porque esos fallos se producen antes de llegar a la ruta de errores de negocio:

HTTP	Condición	Cuerpo
404	El task_id no existe o pertenece a otra cuenta	solo message
404	GET /v1/tasks/{token}/download: el archivo de resultados no está disponible, ha caducado o ya no se puede descargar	solo message
422	GET /v1/tasks/{token}/result: el resultado no está listo; la tarea no ha terminado, el archivo no se ha generado o ha caducado	solo message
422	Los parámetros de la solicitud no superaron la validación	{ "message": …, "errors": { … } }

Para estos casos, ramifica según el estado HTTP. El message es para tus logs y para quien lee un incidente, no para el flujo de control.

Envía Accept: application/json

Estos cuerpos son JSON cuando la solicitud pide JSON. Un cliente que no envía el encabezado Accept puede recibir en su lugar una página de error HTML, algo incómodo de depurar a las 3 de la mañana. Todos los ejemplos de esta documentación envían JSON.

Reintentos

La respuesta correcta ante un fallo depende de si repetir la solicitud podría producir un resultado diferente.

Requiere acción primero

Un reintento sin cambios repite el mismo fallo.

unauthorized, account_banned, invalid_realtime_request, idempotency_key_required, invalid_idempotency_key, idempotency_conflict, empty_input, product_not_found, product_mode_not_supported, invalid_country, too_few_numbers, too_many_numbers, insufficient_balance, realtime_disabled, product_pricing_unavailable

Espera y luego reintenta

Transitorio: la misma solicitud debería funcionar más tarde.

realtime_rate_limited, request_in_progress, detection_capacity_unavailable, realtime_route_unavailable, realtime_fact_cache_unavailable, realtime_rate_limiter_unavailable

Resultado incierto

Es posible que la solicitud se haya aplicado o no. Reintenta con la misma clave.

internal_error