Errors
Every error uses a consistent HTTP status and a body with the same shape. Branch on the code field: it is stable and does not change across versions.
Error shape
HTTP/1.1 400 Bad Request
Request-Id: req_Qm3Xc81ZpRt0aBcYvWsK
{
"error": {
"code": "invalid_request",
"message": "La richiesta non è valida.",
"doc_url": "https://docs.taplogic.it/it/errors#invalid_request",
"param": "from",
"details": [
{ "param": "from", "message": "from deve precedere to." }
],
"request_id": "req_Qm3Xc81ZpRt0aBcYvWsK"
}
}code | Stable code, in English, safe to use in code. |
message | Human-readable text in Italian or English, from Accept-Language. It can change: do not compare it. |
doc_url | This page, at the code's anchor. |
param | The field or header that caused the error, when there is one. |
details | For invalid_request: one item per invalid field. |
request_id | Request identifier, equal to the Request-Id header. Quote it to support. |
Message language
Send Accept-Language: en for English messages. Without it, messages are in Italian.
When to retry
Retry only 429 (after Retry-After) and 5xx (with growing waits). Retried writes must carry the same Idempotency-Key. Other 4xx do not change when repeated.
Every code
| Code | HTTP | Meaning |
|---|---|---|
authentication_required | 401 | No API key provided. Send it in the Authorization header: Bearer tl_live_…. |
invalid_api_key | 401 | The API key is invalid, expired or revoked. |
insufficient_scope | 403 | The API key does not have the scope this operation requires. |
test_mode_unsupported | 403 | This operation is not available with a test key. Use a tl_live_ key. |
resource_missing | 404 | The resource does not exist. |
route_not_found | 404 | This path does not exist in the API. |
invalid_request | 400 | The request is invalid. |
invalid_json | 400 | The request body is not valid JSON. |
invalid_cursor | 400 | The pagination cursor is invalid. |
invalid_api_version | 400 | The version in TapLogic-Version does not exist. |
payload_too_large | 413 | The request body is too large. |
idempotency_key_mismatch | 422 | This Idempotency-Key was already used with a different request. |
idempotency_in_progress | 409 | A request with this Idempotency-Key is still in progress. |
idempotency_replay_unavailable | 409 | The saved response for this Idempotency-Key can no longer be read. Check the state of the resource and use a new key. |
rate_limit_exceeded | 429 | Too many requests. Wait for the time in Retry-After. |
member_is_owner | 409 | The company owner cannot be removed. |
already_member | 409 | This person is already a member of the company. |
invitation_pending | 409 | A pending invitation already exists for this address. |
seats_exhausted | 409 | No seats are available. Free a seat or buy more. |
tag_deactivated | 409 | The tag is deactivated and cannot be changed. |
webhook_url_not_allowed | 400 | The webhook URL must be https and public. |
webhook_limit_reached | 409 | You reached the maximum number of webhook endpoints. |
webhook_disabled | 409 | The endpoint is disabled. Enable it before sending a test event. |
internal_error | 500 | Internal error. Retry: writes with an Idempotency-Key are safe. |