Errores

Cada respuesta de error M2M usa RFC 7807 problem+json. El campo error_code es el identificador estable legible por máquina — haga switch sobre él en su código, nunca sobre el detail legible por humanos.

Esta página lista cada código que los socios pueden recibir, agrupado por dominio.

Forma de la respuesta

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/problem+json

{
  "type": "about:blank",
  "title": "Unprocessable Entity",
  "status": 422,
  "error_code": "DB-FX-410",
  "detail": "FX quote invalid, expired, or not owned",
  "trace_id": "0HN5K8M3F2X4P:00000007",
  "instance": "/api/v1/fxorder/createOrder",
  "errors": {
    "parameters.quote_id": ["Quote expired at 2026-04-28T10:35:00.000Z"]
  }
}

Convención de nombres de código

{NAMESPACE}-{DOMINIO}-{NÚMERO}. Tres namespaces:

El segmento DOMINIO agrupa por área de negocio: FX, TRF (transferencias), WAL (billeteras), CUS (clientes), CMP (cumplimiento), TRD (trading), PAD (Padrón Electoral), MNX (Monex broker externo), AML (anti-lavado de dinero), BRG (pasarela fiat stablecoin), BRI (capa de pasarela stablecoin).

Los rangos de número dentro de un dominio siguen convenciones flexibles:

Guía de reintentos

La bandera retryable abajo refleja la categoría del error mismo. Los problemas de capa de red (5xx, 429) son siempre reintentables sin importar el error_code subyacente. Vea Idempotencia para la matriz completa de decisión de reintentos.

Catálogo por dominio

El catálogo abajo se genera desde <azure-iac>/registry/errors/namespaces/*.yaml y se mantiene en sincronía vía la pipeline de codegen del registro. Si encuentra un código en producción que falta aquí, abra un ticket de soporte — códigos no documentados son un bug de deriva de documentación.

CLIENT-NET — Cliente / red

DB-AML — AML / cumplimiento

DB-STC — stablecoin / pasarela fiat

DB-CMP — Cumplimiento / KYC

DB-CUS — Clientes

DB-FX — Órdenes FX + cotizaciones

DB-MNX — Monex / broker externo

DB-PAD — Padrón Electoral

DB-TRD — Trading / valores

DB-TRF — Transferencias

DB-WAL — Billeteras + saldos

GW-STC — Pasarela stablecoin

Nota sobre títulos en inglés. Los títulos arriba se mantienen en inglés porque el detail y title retornados en el response también están en inglés actualmente; localizar este catálogo por separado introduciría deriva. Cuando ARi habilite localización del response vía Accept-Language, este catálogo se traducirá automáticamente.

Resumen de códigos de estado HTTP

La distinción 400 vs 422 importa para codegen de SDK de socio: violaciones de esquema oneOf son 400 (el cuerpo de la solicitud no encaja con el contrato); violaciones de regla de negocio en una solicitud bien formada son 422 (el cuerpo es válido pero la operación no puede proceder).

Errores a nivel de campo

Cuando un 400 o 422 incluye fallas de validación por campo, aparecen en el objeto errors con clave por ruta de campo punteada:

{
  "status": 400,
  "error_code": "DB-FX-417",
  "detail": "FX order missing required fields",
  "errors": {
    "parameters.origin_currency": ["origin_currency is required"],
    "parameters.destination_currency": ["destination_currency must be 3 characters"]
  }
}

Itere Object.keys(response.errors) para obtener una lista plana de nombres de campo; cada valor es un arreglo de strings con mensajes de validación para ese campo.

Qué registrar en errores

Cada respuesta de error incluye trace_id. Siempre regístrelo del lado cliente. Cuando contacte soporte, incluya el trace_id en su mensaje — es la ruta más rápida a una resolución porque ARi puede consultar inmediatamente las trazas distribuidas desde ese ID.

Forma de línea de log recomendada:

[ERROR] api={endpoint} status={status} error_code={error_code} trace_id={trace_id} attempt={n}/{max}

Vea también

• Autenticación — esquema RFC 7807, mecánica de trace_id
• Idempotencia — matriz de decisión de reintentos por código de estado
• Sandbox — IBANs de prueba determinísticos que ejercitan códigos de error específicos
• Órdenes FX, Transferencias, Broker — ejemplos específicos de uso de errores por dominio