Errors
Every error has the same envelope and a stable code. Branch on the HTTP status and the code, never on the message.
Error envelope
Every error has the same body, whatever the status:
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Request data failed validation rules",
"details": {
"errors": [{ "field": "sender.postal_code", "code": "REQUIRED", "message": "Field is required" }]
}
}
}
codeis stable,UPPER_SNAKEand meant for your code to branch on. It is never reused for another meaning and never removed within a version.messageis human text in theAccept-Languagelanguage. Show it, never parse it.detailsis optional. For a validation error it lists the fields; field paths use the language of the keys you sent. For a5xxit carries acorrelation_idto quote to support.- The envelope keys stay English even when you ask for Italian keys with
ParceLabs-Key-Locale. - A
5xxnever leaks SQL, paths, hosts or carrier payloads.
A normal business answer is not an error: a coupon that does not apply is 200 with valid: false, and a shipment that cannot be refunded is an outcome inside a 200 batch result.
Error codes
| Code | HTTP | Meaning |
|---|---|---|
VALIDATION_ERROR | 400 | A field is missing or invalid. details.errors lists them. |
INVALID_JSON | 400 | The body is not valid JSON. |
IDEMPOTENCY_KEY_REQUIRED | 400 | The operation needs an Idempotency-Key header. |
UNSUPPORTED_VERSION | 400 | The ParceLabs-Version date is unknown. details lists the supported ones. |
API_KEY_MISSING, API_KEY_INVALID | 401 | No credential, or a wrong one. |
API_KEY_EXPIRED | 401 | The key is outside its validity dates. |
IP_NOT_ALLOWED | 403 | The key is limited to other IP addresses. |
ACCOUNT_INACTIVE | 403 | The account is not active. |
FEATURE_NOT_ENABLED | 403 | The function is not enabled for your account: ask support. |
CUSTOMER_OUT_OF_SCOPE | 403 | The customer is not in your network. |
NOT_FOUND, SHIPMENT_NOT_FOUND, CUSTOMER_NOT_FOUND | 404 | It does not exist, or it is not yours. |
OFFER_ALREADY_ORDERED | 409 | This offer was already bought with another idempotency key. |
CUSTOMER_ALREADY_EXISTS, INVITATION_ALREADY_ACCEPTED | 409 | The customer or the invitation is already there. |
IDEMPOTENCY_KEY_IN_USE | 409 | A call with this key is still running. |
VERSION_RETIRED | 410 | The version you asked for is no longer served. |
INSUFFICIENT_CREDIT | 422 | Your prepaid credit does not cover the amount. |
SERVICE_NOT_AVAILABLE | 422 | A requested service is not available; details name the service and the carrier. |
CARRIER_NOT_AVAILABLE | 422 | The carrier cannot be bought through the API. |
IDEMPOTENCY_KEY_REUSED | 422 | The key was used with a different body. |
DAILY_LIMIT_EXCEEDED, RATE_LIMIT_EXCEEDED | 429 | Too many requests. Wait for Retry-After. |
SHIPMENT_CREATION_FAILED, CUSTOMER_CREATION_FAILED, SERVER_ERROR | 500 | Something failed on our side. |
FEATURE_NOT_IMPLEMENTED | 501 | The operation is published but not built yet. |
UPSTREAM_ERROR, UPSTREAM_TIMEOUT | 502, 504 | A system we depend on failed or was too slow. |
What to retry
400,401,403,404,409,410and422will not change if you send the same request again. Fix the request first.429: wait for theRetry-Afterheader.500,502,503,504: retry with growing delays. On a write, send the sameIdempotency-Key: if the first try did go through you get its answer back, not a second purchase.