Errores
Cómo interpretar y manejar los errores de la API.
API v2ActualFormato de error
Los errores HTTP usan una estructura consistente. Usá error.code para manejarlos programáticamente; message está pensado para lectura humana.
| Campo | Descripción |
|---|---|
| code | Código estable para manejar el error desde tu integración. |
| message | Descripción legible del error. |
| requestId | Identificador de la request, útil para soporte y diagnóstico. |
| retryable | Indica si el error puede ser transitorio y tiene sentido volver a intentar. |
| details | Información adicional específica del error, cuando está disponible. |
{
"error": {
"code": "quota_exceeded",
"message": "Account limit exceeded.",
"requestId": "req_example",
"retryable": true,
"details": {
"meter": "module_queries",
"limit": 10,
"used": 10,
"resetAt": "2026-10-01T03:00:00.000Z"
}
}
}Guardá requestId cuando reportes un problema a soporte: permite identificar la request correspondiente.
retryable: true no significa que debas repetir inmediatamente una consulta. Cuando estén disponibles, respetá Retry-After y details.resetAt. En quota_exceeded, esperá al reinicio del cupo o revisá los límites de tu plan.
Para quota_exceeded, details.meter identifica el cupo: plate_queries, module_queries o unique_plates. En rate_limit_exceeded, el valor es requests.
Errores comunes
| Código | HTTP | Qué hacer |
|---|---|---|
| invalid_api_key | 401 | Verificá que estés enviando una API key activa. |
| access_denied | 403 | Tu cuenta no tiene acceso a esa operación o capacidad. |
| invalid_plate | 400 | Verificá el formato de la patente: ABC123 o AB123CD. |
| invalid_request | 400 / 404 | Revisá los parámetros, el body y la ruta solicitada. |
| unsupported_module | 400 | Usá fines, vtv, tax_debt o gnc. |
| duplicate_module | 400 | No repitas el mismo módulo en una solicitud. |
| module_not_enabled | 403 | El módulo no está habilitado para tu cuenta. |
| quota_exceeded | 429 | Alcanzaste el cupo disponible. Revisá el límite y su fecha de reinicio. |
| rate_limit_exceeded | 429 | Esperá el tiempo indicado por Retry-After. |
| operation_not_found | 404 | Verificá el ID de la operación. |
| temporarily_unavailable | 503 | Esperá y volvé a intentar si el error lo indica. |
| internal_error | 500 | Guardá requestId y revisá retryable antes de reintentar. |
Consumo y errores
Los requests rechazados antes de ser aceptados no consumen consultas de patente ni de módulos. Por ejemplo: una patente inválida, un módulo no soportado o falta de cupo.
Una operación ya aceptada puede terminar posteriormente con un error de módulo. En ese caso, el resultado muestra el error dentro del módulo correspondiente.
Errores durante una operación
Una consulta modular puede ser aceptada correctamente y, más tarde, uno de sus módulos puede terminar como failed.
GET /v2/operations/:id puede devolver 200 OK porque pudimos recuperar su estado, mientras el resultado de un módulo contiene:
{
"status": "failed",
"data": null,
"error": {
"code": "module_unavailable",
"message": "No se pudo completar el módulo.",
"retryable": true
}
}Un módulo con status: completed y total: 0 se procesó correctamente y no encontró registros. No es lo mismo que status: failed.