Envelope de error público, catálogo de códigos HTTP/retryable y reglas de no filtración de recursos ajenos.

Errores

Todos los endpoints usan un envelope estable. El status HTTP describe la clase del resultado; error.code es el identificador que debe usar el cliente para tomar decisiones.

Formato

{
  "error": {
    "code": "payment_method_not_found",
    "message": "El método de pago solicitado no existe o no está habilitado para esta API key.",
    "category": "validation",
    "retryable": false,
    "request_id": "req_019f704f89d77e83",
    "details": {}
  }
}

Campo	Uso
`code`	Identificador estable para lógica del cliente.
`message`	Explicación legible; no debe parsearse.
`category`	Grupo general del error.
`retryable`	Indica si repetir podría funcionar sin corregir el request.
`request_id`	Correlación para logs y soporte.
`details`	Información estructurada y no sensible, cuando aplica.

Un error de validación puede incluir detalles:

{
  "error": {
    "code": "invalid_request",
    "message": "La solicitud no cumple el contrato.",
    "category": "validation",
    "retryable": false,
    "request_id": "req_019f704f89d77e83",
    "details": {
      "fields": [
        {
          "path": "amount.value",
          "message": "Debe ser un string decimal positivo."
        }
      ]
    }
  }
}

Catálogo

Código	HTTP	Retryable	Descripción
`invalid_request`	400	No	El request no cumple el contrato.
`invalid_credentials`	401	No	Email o contraseña incorrectos.
`invalid_api_key`	401	No	API key inválida, expirada o revocada.
`invalid_refresh_token`	401	No	Refresh token inválido, expirado o revocado.
`unauthorized`	401	No	Falta autenticación de usuario.
`insufficient_scope`	403	No	La API key no posee el scope requerido.
`insufficient_role`	403	No	El usuario no tiene el rol requerido.
`user_not_found`	404	No	El usuario no existe.
`payment_method_not_found`	404	No	El método no existe o no está habilitado para la credencial.
`idempotency_key_required`	400	No	Falta la clave de idempotencia.
`idempotency_key_reused`	409	No	La clave fue usada con otro request.
`external_reference_conflict`	409	No	Ya existe un pago con esa `external_reference` para la API key.
`unsupported_currency`	422	No	El método no soporta la moneda.
`processor_declined`	402	No	El procesador rechazó la operación.
`processor_timeout`	504	Sí	No se obtuvo una respuesta concluyente.
`processor_unavailable`	503	Sí	El procesador no está disponible.
`connector_configuration_invalid`	500	No	La configuración publicada del método no es ejecutable.
`request_timeout`	504	Sí	La solicitud excedió el tiempo de espera.
`internal_error`	500	Sí	Error interno no esperado.

Estrategia de manejo

Guardar request_id, endpoint, fecha UTC y referencia externa.
Si retryable es false, corregir credenciales, permisos, estado o payload antes de repetir.
Si retryable es true y es una escritura, repetir con la misma Idempotency-Key y el mismo body.
Aplicar backoff con límite; no crear una operación lógica nueva por un timeout.
Para pagos inciertos, consultar el recurso o esperar un webhook.

processor_declined es un rechazo concluyente. processor_timeout, processor_unavailable, request_timeout e internal_error pueden ser transitorios, pero retryable: true no garantiza éxito ni autoriza cambiar la clave de idempotencia.

Los errores connector_configuration_invalid son de configuración. Una aplicación de cobro debe escalarlos al administrador; no se corrigen cambiando el body del pago.

Seguridad

No diferenciar públicamente:

recurso inexistente;
recurso de otro owner;
recurso no habilitado para la API key.

Los tres casos usan el mismo error de recurso no encontrado.

Esta indistinguibilidad evita confirmar la existencia de recursos de otro owner.