This page is the global error-code dictionary for the API. Every error response carries a stable, machine-readable code your client must use to branch logic. The detail is human-readable and translated; the code never changes and is never translated.

For a gentle intro to the error envelope, see Errors. For related flows, see Idempotency, Rate limits, and Webhooks architecture.

Response shape

Every error response follows the standard JSON:API envelope — an errors array and a meta object. A single response can carry several errors when applicable (typically for field validation).

{
  "errors": [
    {
      "status": "422",
      "code": "phone_not_verified",
      "detail": "Phone is not verified.",
      "source": { "pointer": "/data/attributes/phone" },
      "meta": { "masked_phone": "+52 55 ••••1234" }
    }
  ],
  "meta": {
    "version": "1.47.0",
    "api_version": "v1",
    "request_id": "a1b2c3d4e5f6",
    "datetime": { "timezone": "UTC", "format": "ISO 8601" }
  }
}

Global rules

• code is stable, snake_case ASCII, and never translated. Branch client logic on this field.
• detail is human-readable and translated per Accept-Language (es / en).
• status is the HTTP status code as a string (matches the response status).
• source.pointer (optional) is a JSON Pointer (RFC 6901) to the request-body field that failed.
• Per-error meta is optional — some codes attach context (e.g. masked_phone, retry_after_seconds).
• A 422 response may include several errors — one per invalid field.
• meta.request_id correlates with server logs — always include it when reporting a bug.

Common HTTP statuses

Taxonomy by category

Authentication & session

OTP, 2FA, and verification

Registration & account

Generic field validation

These codes are emitted by Support\Validator and may appear on any endpoint with a body.

Idempotency

See Idempotency for the full contract.

SPEI transfer validation

Applies to POST /v1/validate, POST /v1/validate-ocr, and the bulk validation pipeline.

Async-validation terminal codes

These codes appear in validations.error_code when an async validation lands in terminal state error or failed. See Async validations and Retry policy.

Beneficiaries

Bulk imports (validations + beneficiaries)

Plan & billing

Finance

Webhooks & notifications

Rate limit

See Rate limits for the full headers + buckets convention.

Generic resources

Admin (internal operation)

These codes come from /v1/admin/* endpoints and require a permissioned role. The complete list covers queues, scheduled tasks, services, migrations, seeders, tests, plans, security, and i18n panels. The most recurring ones are listed below; the rest follow the convention <domain>_<action>_failed for 5xx and <domain>_<action>_invalid for 4xx.

Reporting an error

When something fails unexpectedly:

1. Capture meta.request_id from the response.
2. Note the code and the status.
3. If it's a repeatable 5xx, open a support ticket including both.

The request_id correlates with server-side logs and lets the team trace the exact cause without you having to reproduce it.