Formato JSON
code y message están en la raíz. field y details son opcionales. No existe una envoltura error.code. Usa code para decidir y no dependas de un mensaje literal o de su idioma. Un proxy puede devolver HTML u otro body: comprueba primero el estado HTTP.
Estados HTTP
Los nombres HTTP siguientes no se traducen. Las explicaciones sí cambian con el idioma; los identificadores de la API se conservan.Causas y recuperación
400 Bad Request
missing_field, invalid_format, unknown_parameter, invalid_base, invalid_against. Corrige la entrada; no reintentes la misma consulta.
401 Unauthorized
invalid_api_key o key_revoked. Revisa la credencial del servidor.
402 Payment Required
feature_not_in_plan: consulta details.feature y details.current_plan. Es una restricción de plan, no un fallo transitorio.
403 Forbidden
email_not_verified, account_inactive, endpoint_disabled o history_out_of_retention. Resuelve la causa indicada, sin bucle de reintentos.
404 Not Found
resource_not_found, bank_not_found o bcv_snapshot_unavailable, según el endpoint. Revisa recurso, ruta y cobertura.
406 Not Acceptable
format_not_available: usa JSON o XML cuando el CSV no puede representar varias colecciones.
422 Unprocessable Entity
reference_unavailable, compared_unavailable o no_route con filtro de antigüedad. No inventes un resultado; aplica tu política explícita de indisponibilidad.
429 Too Many Requests
rate_limit_exceeded: distingue el scope burst, monthly o ausente. Sigue cuotas y límites.
500 Internal Server Error
internal_error: fallo interno. Para GET, reintentos acotados con backoff y un plazo total.
502 Bad Gateway
Puede proceder de una fuente o un proxy. Conserva el estado aunque el body no sea JSON; limita los reintentos de GET.503 Service Unavailable
Servicio o datos no disponibles; puede aparecerservice_unavailable. No repitas automáticamente un POST de resultado incierto.
Reportar un fallo
Incluye ruta, hora UTC, estado ycode, sin claves ni secretos, al contactar con soporte. Revisa también el estado del servicio.