Errors

When something goes wrong, TRUED answers with a standard error body (RFC 9457, application/problem+json). The message is plain English and says what to do next.

{
  "type": "https://docs.trued.io/errors/400",
  "title": "Bad request",
  "status": 400,
  "detail": "Some parameters were not accepted. See \"errors\" for each one.",
  "errors": [
    { "field": "limt", "message": "This parameter is not supported on this endpoint." }
  ],
  "request_id": "req_9k2LmQ"
}

Field	Meaning
`type`	A link that identifies the kind of error. It ends in the status code.
`title`	A short summary.
`status`	The HTTP status, repeated in the body.
`detail`	What happened and what to do.
`request_id`	The id of this request. Also sent as the `X-Request-Id` header.
`errors`	For a `400` about parameters, one row per parameter that was wrong, with `field` and `message`.

Statuses

Status	When	What to do
`400`	A parameter is wrong or unknown, a cursor does not match its filters, or the key was put in the URL	Fix the request. Do not retry it unchanged.
`401`	No key, or the key is not valid (unknown, revoked or expired)	Check the key in TRUED. Do not retry.
`403`	The key does not have the permission this endpoint needs	Create a key with that permission.
`404`	The path does not exist, or the id is not in your workspace	Check the id. TRUED does not say whether an id exists in another workspace.
`405`	The method is not allowed. The API is read only: only `GET`, `HEAD` and `OPTIONS`	Use `GET`.
`429`	Too many requests	Wait for the number of seconds in `Retry-After`, then retry. See Rate limits.
`500`	Something went wrong at TRUED. TRUED's team is alerted automatically	Retry after a short wait. If it continues, contact support with the `request_id`.
`503`	The service is briefly unavailable	Retry with a growing wait.

Retrying safely

Every endpoint only reads data, so any request can be retried without side effects. Retry 429, 500 and 503 with a growing wait (for example 1, 2, 4, 8 seconds). Never retry 400, 401, 403 or 404 unchanged: the answer will be the same.

Always log the request id

Log the request_id (or the X-Request-Id header) of any request that failed. When you contact TRUED support, that id lets the team find the exact request in seconds.

curl -i https://api.trued.io/v1/invoices/inv_missing \
  -H "Authorization: Bearer $TRUED_API_KEY"