Errors

Failed API requests return JSON error responses. Every API response also includes a Request-Id header; error responses repeat the same value as request_id in the JSON body.

Use the HTTP status code for broad handling, the stable code field for application-specific behavior, and the request ID when debugging or contacting support.

Example error

This example shows the response for an unsupported hellomateo-version header:

curl "https://api.getmateo.com/v1/contacts" \
  --header "Authorization: Bearer <your_api_token>" \
  --header "hellomateo-version: 1900-01-01"

HTTP/1.1 400 Bad Request
Request-Id: 3f31b3d8-9f1e-4c7f-8b6f-0123456789ab
Content-Type: application/json

{
  "name": "APIError",
  "message": "Unsupported hellomateo-version header",
  "code": "INVALID_VERSION_HEADER",
  "is_transient": false,
  "timestamp": "2026-01-01T00:00:00.000Z",
  "status_code": 400,
  "contact_support": false,
  "request_id": "3f31b3d8-9f1e-4c7f-8b6f-0123456789ab",
}

How to handle errors

Use the HTTP status code to choose the broad handling path. 4xx errors usually require changing the request before retrying. 5xx errors mean hellomateo could not complete an otherwise valid request.

Use the stable code field for application-specific behavior. Do not branch on message, which is intended for humans reading logs or debugging a request.

Use is_transient to decide whether retrying the same request may help. If is_transient is false, retrying without changing the request is not expected to succeed.

Use the Request-Id header or request_id body field when debugging failed requests. See Request IDs for more details.

Status code classes

• 2xx: the request succeeded.
• 4xx: the request was invalid or cannot be completed without caller action.
• 5xx: hellomateo could not complete an otherwise valid request.

Error fields

Optional fields such as hint or context may be present for specific errors. Do not require optional fields unless the endpoint and error code document them.

Debugging failed requests

When you contact hellomateo support about a failed API request, include:

• the Request-Id response header or request_id error field
• the endpoint and HTTP method
• the error code, when available
• the timestamp, when available