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 di Accept-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 un 5xx contiene un correlation_id da indicare al supporto.
  • Le chiavi della busta restano in inglese anche se chiedi chiavi italiane con ParceLabs-Key-Locale.
  • Un 5xx non 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

CodiceHTTPSignificato
VALIDATION_ERROR400Un campo manca o non è valido. details.errors li elenca.
INVALID_JSON400Il corpo non è JSON valido.
IDEMPOTENCY_KEY_REQUIRED400L'operazione richiede l'header Idempotency-Key.
UNSUPPORTED_VERSION400La data di ParceLabs-Version è sconosciuta. details elenca le supportate.
API_KEY_MISSING, API_KEY_INVALID401Credenziale assente o errata.
API_KEY_EXPIRED401La chiave è fuori dalle sue date di validità.
IP_NOT_ALLOWED403La chiave è limitata ad altri indirizzi IP.
ACCOUNT_INACTIVE403L'account non è attivo.
FEATURE_NOT_ENABLED403La funzione non è abilitata per il tuo account: chiedi al supporto.
CUSTOMER_OUT_OF_SCOPE403Il cliente non fa parte della tua rete.
NOT_FOUND, SHIPMENT_NOT_FOUND, CUSTOMER_NOT_FOUND404Non esiste, oppure non è tuo.
OFFER_ALREADY_ORDERED409Questa offerta è già stata acquistata con un'altra chiave di idempotenza.
CUSTOMER_ALREADY_EXISTS, INVITATION_ALREADY_ACCEPTED409Il cliente o l'invito esiste già.
IDEMPOTENCY_KEY_IN_USE409Una chiamata con questa chiave è ancora in corso.
VERSION_RETIRED410La versione richiesta non è più servita.
INSUFFICIENT_CREDIT422Il credito prepagato non copre l'importo.
SERVICE_NOT_AVAILABLE422Un servizio richiesto non è disponibile; details indicano servizio e corriere.
CARRIER_NOT_AVAILABLE422Il corriere non si può acquistare via API.
IDEMPOTENCY_KEY_REUSED422La chiave è stata usata con un corpo diverso.
DAILY_LIMIT_EXCEEDED, RATE_LIMIT_EXCEEDED429Troppe richieste. Attendi Retry-After.
SHIPMENT_CREATION_FAILED, CUSTOMER_CREATION_FAILED, SERVER_ERROR500Qualcosa è andato storto da parte nostra.
FEATURE_NOT_IMPLEMENTED501L'operazione è pubblicata ma non ancora realizzata.
UPSTREAM_ERROR, UPSTREAM_TIMEOUT502, 504Un sistema da cui dipendiamo ha fallito o è stato troppo lento.

Cosa riprovare

  • 400, 401, 403, 404, 409, 410 e 422 non cambiano se invii di nuovo la stessa richiesta. Correggi prima la richiesta.
  • 429: attendi l'header Retry-After.
  • 500, 502, 503, 504: riprova con attese crescenti. In una scrittura invia la stessa Idempotency-Key: se il primo tentativo era andato a buon fine ottieni la sua risposta, non un secondo acquisto.

Was this page helpful?

Was this page helpful?