Errori
Ogni errore ha la stessa busta e un codice stabile. Ragiona sullo status HTTP e sul codice, mai sul messaggio.
Busta dell'errore
Ogni errore ha lo stesso corpo, qualunque sia lo status:
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Request data failed validation rules",
"details": {
"errors": [{ "field": "sender.postal_code", "code": "REQUIRED", "message": "Field is required" }]
}
}
}
codeè stabile,UPPER_SNAKE, pensato perché il tuo codice ci si basi. Non è mai riusato per un altro significato e mai rimosso all'interno di una versione.messageè testo leggibile nella lingua diAccept-Language. Mostralo, non interpretarlo mai.detailsè facoltativo. Per un errore di validazione elenca i campi; i percorsi dei campi usano la lingua delle chiavi che hai inviato. Per un5xxcontiene uncorrelation_idda indicare al supporto.- Le chiavi della busta restano in inglese anche se chiedi chiavi italiane con
ParceLabs-Key-Locale. - Un
5xxnon rivela mai SQL, percorsi, host o payload dei corrieri.
Una normale risposta di business non è un errore: un coupon che non si applica è 200 con valid: false, e una spedizione che non si può stornare è un outcome dentro un risultato 200.
Codici di errore
| Codice | HTTP | Significato |
|---|---|---|
VALIDATION_ERROR | 400 | Un campo manca o non è valido. details.errors li elenca. |
INVALID_JSON | 400 | Il corpo non è JSON valido. |
IDEMPOTENCY_KEY_REQUIRED | 400 | L'operazione richiede l'header Idempotency-Key. |
UNSUPPORTED_VERSION | 400 | La data di ParceLabs-Version è sconosciuta. details elenca le supportate. |
API_KEY_MISSING, API_KEY_INVALID | 401 | Credenziale assente o errata. |
API_KEY_EXPIRED | 401 | La chiave è fuori dalle sue date di validità. |
IP_NOT_ALLOWED | 403 | La chiave è limitata ad altri indirizzi IP. |
ACCOUNT_INACTIVE | 403 | L'account non è attivo. |
FEATURE_NOT_ENABLED | 403 | La funzione non è abilitata per il tuo account: chiedi al supporto. |
CUSTOMER_OUT_OF_SCOPE | 403 | Il cliente non fa parte della tua rete. |
NOT_FOUND, SHIPMENT_NOT_FOUND, CUSTOMER_NOT_FOUND | 404 | Non esiste, oppure non è tuo. |
OFFER_ALREADY_ORDERED | 409 | Questa offerta è già stata acquistata con un'altra chiave di idempotenza. |
CUSTOMER_ALREADY_EXISTS, INVITATION_ALREADY_ACCEPTED | 409 | Il cliente o l'invito esiste già. |
IDEMPOTENCY_KEY_IN_USE | 409 | Una chiamata con questa chiave è ancora in corso. |
VERSION_RETIRED | 410 | La versione richiesta non è più servita. |
INSUFFICIENT_CREDIT | 422 | Il credito prepagato non copre l'importo. |
SERVICE_NOT_AVAILABLE | 422 | Un servizio richiesto non è disponibile; details indicano servizio e corriere. |
CARRIER_NOT_AVAILABLE | 422 | Il corriere non si può acquistare via API. |
IDEMPOTENCY_KEY_REUSED | 422 | La chiave è stata usata con un corpo diverso. |
DAILY_LIMIT_EXCEEDED, RATE_LIMIT_EXCEEDED | 429 | Troppe richieste. Attendi Retry-After. |
SHIPMENT_CREATION_FAILED, CUSTOMER_CREATION_FAILED, SERVER_ERROR | 500 | Qualcosa è andato storto da parte nostra. |
FEATURE_NOT_IMPLEMENTED | 501 | L'operazione è pubblicata ma non ancora realizzata. |
UPSTREAM_ERROR, UPSTREAM_TIMEOUT | 502, 504 | Un sistema da cui dipendiamo ha fallito o è stato troppo lento. |
Cosa riprovare
400,401,403,404,409,410e422non cambiano se invii di nuovo la stessa richiesta. Correggi prima la richiesta.429: attendi l'headerRetry-After.500,502,503,504: riprova con attese crescenti. In una scrittura invia la stessaIdempotency-Key: se il primo tentativo era andato a buon fine ottieni la sua risposta, non un secondo acquisto.