Errori
Ogni errore usa un codice HTTP coerente e un corpo con la stessa forma. Programma sul campo code: è stabile e non cambia tra le versioni.
Forma dell'errore
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 | Codice stabile, in inglese, da usare nel codice. |
message | Spiegazione leggibile in italiano o inglese, secondo Accept-Language. Può cambiare: non confrontarla. |
doc_url | Questa pagina, all'ancora del codice. |
param | Il campo o l'intestazione che ha causato l'errore, quando c'è. |
details | Per invalid_request: un elemento per ogni campo non valido. |
request_id | Identificativo della richiesta, uguale all'intestazione Request-Id. Citalo all'assistenza. |
Lingua dei messaggi
Invia Accept-Language: en per i messaggi in inglese. Senza, i messaggi sono in italiano.
Quando ritentare
Ritenta solo 429 (dopo Retry-After) e 5xx (con attesa crescente). Le scritture ritentate devono portare la stessa Idempotency-Key. Gli altri 4xx non cambiano ripetendo la richiesta.
Tutti i codici
| Codice | HTTP | Significato |
|---|---|---|
authentication_required | 401 | Manca la chiave API. Inviala nell'intestazione Authorization: Bearer tl_live_…. |
invalid_api_key | 401 | La chiave API non è valida, è scaduta o è stata revocata. |
insufficient_scope | 403 | La chiave API non ha l'ambito richiesto per questa operazione. |
test_mode_unsupported | 403 | Questa operazione non è disponibile con una chiave di test. Usa una chiave tl_live_. |
resource_missing | 404 | La risorsa non esiste. |
route_not_found | 404 | Questo percorso non esiste nell'API. |
invalid_request | 400 | La richiesta non è valida. |
invalid_json | 400 | Il corpo della richiesta non è JSON valido. |
invalid_cursor | 400 | Il cursore di paginazione non è valido. |
invalid_api_version | 400 | La versione indicata in TapLogic-Version non esiste. |
payload_too_large | 413 | Il corpo della richiesta è troppo grande. |
idempotency_key_mismatch | 422 | Questa Idempotency-Key è già stata usata con una richiesta diversa. |
idempotency_in_progress | 409 | Una richiesta con questa Idempotency-Key è ancora in corso. |
idempotency_replay_unavailable | 409 | La risposta salvata per questa Idempotency-Key non è più leggibile. Controlla lo stato della risorsa e usa una chiave nuova. |
rate_limit_exceeded | 429 | Troppe richieste. Attendi il tempo indicato in Retry-After. |
member_is_owner | 409 | Il titolare dell'azienda non si può rimuovere. |
already_member | 409 | Questa persona fa già parte dell'azienda. |
invitation_pending | 409 | Esiste già un invito in attesa per questo indirizzo. |
seats_exhausted | 409 | Non ci sono posti liberi. Libera un posto o acquistane altri. |
tag_deactivated | 409 | Il tag è disattivato e non si può modificare. |
webhook_url_not_allowed | 400 | L'indirizzo del webhook deve essere https e pubblico. |
webhook_limit_reached | 409 | Hai raggiunto il numero massimo di endpoint webhook. |
webhook_disabled | 409 | L'endpoint è disattivato. Riattivalo prima dell'invio di prova. |
internal_error | 500 | Errore interno. Riprova: le scritture con Idempotency-Key sono sicure. |