Errors

Every error response in the API v2 has the same shape: an HTTP status code, and a JSON body with a stable code you can rely on in your integration.

Error body

{
  "data": {
    "code": "NOT_FOUND",
    "message": "Article not found"
  },
  "meta": {
    "trace_id": "9f86d081884c7d659a2feaa0c55ad01568f3a1c2b4d5e"
  }
}

Some errors carry extra fields in data or meta with more context. Ignore the fields you do not use.

Error codes

A 4xx status without its own code in this table returns BAD_REQUEST, and a 5xx status without its own code returns INTERNAL_ERROR. The HTTP status in the response is always the real one, so check both when you need to tell them apart.

Validation errors

A 422 lists each invalid field in data.errors, keyed by the field name:

{
  "data": {
    "code": "VALIDATION_FAILED",
    "message": "The given data was invalid.",
    "errors": {
      "document_type": "The document_type field is required",
      "document_number": "The document_number field is required"
    }
  },
  "meta": {
    "trace_id": "9f86d081884c7d659a2feaa0c55ad01568f3a1c2b4d5e"
  }
}

The value of each field is a message or a list of messages. When the request is rejected without a specific field, data.errors is an empty array or is not present.

Trace ID

Every response, successful or not, includes the X-Trace-Id header. In error responses the same value is also in meta.trace_id.