An API error always arrives in the same document: an errors array and a meta object. The general structure is described in the response shape; this page covers the contents of each error entry and how to handle it.

The full inventory of codes, with the meaning of each one, lives in the error taxonomy.

Fields of an entry

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

What is stable and what is not

The code neither changes nor gets translated: it is the contract. The detail changes with the language and may be reworded between releases without notice, because it is text to be read, not compared.

An integration branching on detail works until someone requests the other language or a sentence is rewritten. It is the most common mistake when consuming this API, and the quietest: it does not fail in testing, it fails in production.

Several errors in one response

A validation 422 returns one entry per invalid field, each with its own source.pointer:

"errors": [
  { "status": "422", "code": "required", "detail": "The fecha field is required.",
    "source": { "pointer": "/data/attributes/fecha" } },
  { "status": "422", "code": "invalid_clabe_checksum", "detail": "The control digit does not match.",
    "source": { "pointer": "/data/attributes/cuenta_beneficiaria" } }
]

The correct traversal covers the whole array. Reading only errors[0] hides the remaining fields that need fixing, and forces a retry cycle the response had already resolved in one.

Meaning of each HTTP code

The 5xx codes and 429 are retryable; the remaining 4xx are not, because the request must be corrected before being repeated.

Diagnosis

Every error response includes meta.request_id. That value identifies the specific request in the system logs and is the data required to investigate an individual case.