Errores

Toda respuesta de error sigue el mismo formato:


{
  "error": {
    "code": "validation_failed",
    "message": "El campo email es obligatorio.",
    "details": [
      { "field": "email", "issue": "missing" }
    ],
    "request_id": "req_abc123",
    "doc_url": "https://docs.ministrium.com/es/api/errores/#validation_failed"
  }
}

request_id es crítico: inclúyalo siempre en tickets de soporte para que podamos buscar el log exacto.

Códigos HTTP

HTTP	Significado
`200`	OK
`201`	Created
`204`	No Content (DELETE exitoso)
`400`	Bad Request (sintaxis o validación)
`401`	Unauthorized (token inválido o ausente)
`403`	Forbidden (token válido pero rol/scope insuficiente)
`404`	Not Found
`409`	Conflict (ej. email duplicado)
`422`	Unprocessable Entity (validación de negocio)
`429`	Rate limited
`500`	Server error
`503`	Service unavailable (mantenimiento)

Códigos de error de Ministrium

code	Cuándo
`validation_failed`	Falta o es inválido un campo. `details` lista cada problema.
`unauthorized`	Sin token o token expirado.
`token_revoked`	El token fue revocado explícitamente.
`scope_insufficient`	Token válido pero sin scope requerido.
`tenant_not_found`	Cabecera `X-Tenant` apunta a tenant inexistente.
`tenant_inactive`	Tenant suspendido por billing u otro motivo.
`resource_not_found`	El ID solicitado no existe (o no es visible al token).
`conflict`	Crear con un identificador único ya tomado (email duplicado, slug).
`rate_limited`	Cuotas de API superadas. `Retry-After` en cabecera.
`stripe_error`	Stripe rechazó la transacción. `details.stripe_code` con el detalle.
`internal_error`	Bug. Reportar con `request_id`.

Validación múltiple

Si hay varios problemas en un mismo request, todos se reportan:


{
  "error": {
    "code": "validation_failed",
    "message": "3 campos inválidos.",
    "details": [
      { "field": "email", "issue": "invalid_format" },
      { "field": "phone", "issue": "missing" },
      { "field": "campus_id", "issue": "not_found" }
    ]
  }
}

Localización de mensajes

message se traduce según Accept-Language:


Accept-Language: es-MX  →  "El campo email es obligatorio."
Accept-Language: en-US  →  "Field email is required."

code y details[*].field siempre en inglés (estables para parsing).

Reintentos

Código	Reintentar
`5xx`, `408`, `429`	Sí, con backoff exponencial
`4xx` (excepto `429`)	NO. Indica error del cliente.

Backoff sugerido: min(2^retries * 100ms, 30s) con jitter ± 20%.

Mantenimiento programado

Si Ministrium entra en mantenimiento, las llamadas reciben 503 con cabecera Retry-After: <segundos>. Esto se anuncia con 7 días de antelación en Status.

Errores de Stripe

Cuando una operación involucra Stripe (donación, payout) y falla, devolvemos 402 Payment Required o 409 Conflict con detalles:


{
  "error": {
    "code": "stripe_error",
    "message": "La tarjeta fue rechazada por el banco emisor.",
    "details": {
      "stripe_code": "card_declined",
      "decline_code": "insufficient_funds",
      "stripe_request_id": "req_xyz789"
    }
  }
}

stripe_request_id permite cruzar con el dashboard de Stripe.