Errors

Every error response follows the same format:


{
  "error": {
    "code": "validation_failed",
    "message": "Field email is required.",
    "details": [
      { "field": "email", "issue": "missing" }
    ],
    "request_id": "req_abc123",
    "doc_url": "https://docs.ministrium.com/en/api/errors/#validation_failed"
  }
}

request_id is critical: always include it in support tickets so we can find the exact log.

HTTP codes

HTTP	Meaning
`200`	OK
`201`	Created
`204`	No Content (successful DELETE)
`400`	Bad Request (syntax or validation)
`401`	Unauthorized (invalid or missing token)
`403`	Forbidden (valid token, insufficient role/scope)
`404`	Not Found
`409`	Conflict (e.g. duplicate email)
`422`	Unprocessable Entity (business validation)
`429`	Rate limited
`500`	Server error
`503`	Service unavailable (maintenance)

Ministrium error codes

code	When
`validation_failed`	A field is missing or invalid. `details` lists each.
`unauthorized`	No token or expired.
`token_revoked`	Token explicitly revoked.
`scope_insufficient`	Valid token but missing required scope.
`tenant_not_found`	`X-Tenant` header points to a non-existent tenant.
`tenant_inactive`	Tenant suspended for billing or other reason.
`resource_not_found`	Requested ID doesn’t exist (or isn’t visible to the token).
`conflict`	Create with a unique identifier already taken (duplicate email, slug).
`rate_limited`	API quotas exceeded. `Retry-After` in header.
`stripe_error`	Stripe rejected the transaction. `details.stripe_code` with detail.
`internal_error`	Bug. Report with `request_id`.

Multi-validation

If a single request has multiple problems, all are reported:


{
  "error": {
    "code": "validation_failed",
    "message": "3 invalid fields.",
    "details": [
      { "field": "email", "issue": "invalid_format" },
      { "field": "phone", "issue": "missing" },
      { "field": "campus_id", "issue": "not_found" }
    ]
  }
}

Message localization

message is translated per Accept-Language:


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

code and details[*].field always in English (stable for parsing).

Retries

Code	Retry
`5xx`, `408`, `429`	Yes, exponential backoff
`4xx` (except `429`)	NO. Client error.

Suggested backoff: min(2^retries * 100ms, 30s) with ± 20% jitter.

Scheduled maintenance

If Ministrium enters maintenance, calls receive 503 with header Retry-After: <seconds>. This is announced 7 days in advance at Status.

Stripe errors

When an operation involves Stripe (donation, payout) and fails, we return 402 Payment Required or 409 Conflict with details:


{
  "error": {
    "code": "stripe_error",
    "message": "Card was declined by the issuing bank.",
    "details": {
      "stripe_code": "card_declined",
      "decline_code": "insufficient_funds",
      "stripe_request_id": "req_xyz789"
    }
  }
}

stripe_request_id lets you cross-reference with the Stripe dashboard.