Errors
All errors are returned as application/problem+json (RFC 9457) with a stable, machine-readable code. Branch on code (or the HTTP status), never on human-readable text.
Error shape
HTTP/1.1 404 Not Found
Content-Type: application/problem+json
X-Request-ID: 7d1e9c2a-3b4f-4c5d-8e6f-9a0b1c2d3e4f
X-API-Version: 1.0.0
{
"type": "https://docs.talero.dk/problems/not_found",
"title": "Resource not found",
"status": 404,
"detail": "Invoice not found",
"code": "not_found"
}| Field | Description |
|---|---|
type | URI of the problem documentation page on this site. |
title | Short human-readable summary. Stable per code, but not for machine use. |
status | The HTTP status code, repeated in the body. |
detail | Human-readable explanation specific to this occurrence. May change; do not parse. |
code | Stable machine-readable identifier. Branch on this. |
Error codes
| Code | Status | Meaning |
|---|---|---|
invalid_request | 400 | The request is malformed: invalid JSON, missing or invalid parameters, malformed UUIDs or dates, or a missing Idempotency-Key. |
unauthorized | 401 | Missing, invalid, expired or revoked credentials. |
forbidden | 403 | Valid credentials, but the granted scopes do not permit this operation. |
not_found | 404 | The resource does not exist or belongs to another company. |
rate_limited | 429 | Too many requests in the current window. Retry after Retry-After seconds. |
internal_error | 500 | Unexpected server error. Safe to retry with backoff. |
service_unavailable | 503 | A dependency is temporarily unavailable. Retry with backoff. |
X-Request-ID
Every response — success or error — carries an X-Request-ID header identifying that exact request in Talero's logs. Log it with your own request records, and quote it when contacting support: it lets us find the request without any guesswork.
Responses also carry X-API-Version (currently 1.0.0) and the rate limit headers.
Handling errors
- 4xx errors are yours to fix — retrying the identical request will fail again (except
429, which succeeds after the window resets). - 5xx errors are transient — retry with exponential backoff. Creation retries are safe because of idempotency keys.
- OAuth token endpoint errors follow RFC 6749 (
{"error": "...", "error_description": "..."}) rather than problem+json.