Errori

Quando una richiesta fallisce, l’API restituisce uno stato HTTP diverso da 2xx e un corpo JSON con un singolo oggetto error. Il code è un identificatore stabile e leggibile dalle macchine; ramifica su di esso anziché sul message leggibile dalle persone.

Envelope di errore

{
  "error": {
    "code": "not_found",
    "message": "No company matches that identifier.",
    "requestId": "req_018f9c2e7b7a7c3e9a1b2c3d4e5f6a7b",
    "details": [
      { "path": "path.taxId", "message": "Required" }
    ]
  }
}

string

Un codice di errore stabile dalla tabella qui sotto. L’insieme dei codici possibili è enumerato anche nella tua specifica OpenAPI.

string

Una descrizione leggibile. Può cambiare tra le release - non basarti su di essa a livello di codice.

string

L’id della richiesta, uguale all’header X-Request-Id. Citalo nelle richieste di supporto.

object[]

Presente solo per gli errori di validazione (invalid_params). Ogni voce ha un path (con prefisso path., query. o body. per indicare dove si trovava il valore non valido) e un message.

Codici di errore

Codice	HTTP	Significato
`missing_api_key`	`401`	Nessun bearer token nell’header `Authorization`.
`invalid_api_key`	`401`	La API key non è riconosciuta.
`credits_exhausted`	`402`	Il tuo saldo crediti è esaurito.
`limit_reached`	`402`	La tua soglia d’uso per il periodo corrente è raggiunta.
`client_not_configured`	`403`	La key è valida ma la sua organizzazione non ha l’accesso all’API configurato.
`not_entitled`	`403`	Il tuo piano non include questo endpoint.
`unknown_endpoint`	`404`	Rotta inesistente.
`not_found`	`404`	La richiesta era valida ma nessuna azienda corrisponde all’identificatore. Non addebitata.
`invalid_params`	`422`	Un parametro di path o query non ha superato la validazione. Vedi `details`.
`rate_limited`	`429`	Hai superato il tuo rate limit. Vedi `Retry-After`.
`internal_error`	`500`	Si è verificato un errore imprevisto.
`upstream_error`	`502`	La fonte dati a monte ha restituito un errore.
`auth_unavailable`	`503`	La verifica della key è temporaneamente non disponibile. Riprova dopo una breve attesa.
`entitlement_unavailable`	`503`	La verifica dei diritti è temporaneamente non disponibile. Riprova dopo una breve attesa.
`upstream_timeout`	`504`	La fonte dati a monte non ha risposto in tempo.

Un not_found (nessuna azienda corrispondente) non viene mai addebitato. Nemmeno le richieste che falliscono prima di raggiungere la fonte dati - inclusi gli errori di validazione, rate limit e diritti.

Riprovare

429 e i codici 5xx di disponibilità del servizio (auth_unavailable, entitlement_unavailable, upstream_timeout e upstream_error transitori) si possono riprovare in sicurezza. Quando è presente un header Retry-After, attendi almeno quel numero di secondi; altrimenti usa un backoff esponenziale. I codici 4xx diversi da 429 indicano un problema con la richiesta o con il piano e non avranno successo riprovando.

Per iniziare

Endpoint di esempio

Riferimento interattivo

Riferimento

Envelope di errore

Codici di errore

Riprovare

​Envelope di errore

​Codici di errore

​Riprovare

Envelope di errore

Codici di errore

Riprovare