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" }]
    }
  }
}
  • code is stable, UPPER_SNAKE and meant for your code to branch on. It is never reused for another meaning and never removed within a version.
  • message is human text in the Accept-Language language. Show it, never parse it.
  • details is optional. For a validation error it lists the fields; field paths use the language of the keys you sent. For a 5xx it carries a correlation_id to quote to support.
  • The envelope keys stay English even when you ask for Italian keys with ParceLabs-Key-Locale.
  • A 5xx never 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

CodeHTTPMeaning
VALIDATION_ERROR400A field is missing or invalid. details.errors lists them.
INVALID_JSON400The body is not valid JSON.
IDEMPOTENCY_KEY_REQUIRED400The operation needs an Idempotency-Key header.
UNSUPPORTED_VERSION400The ParceLabs-Version date is unknown. details lists the supported ones.
API_KEY_MISSING, API_KEY_INVALID401No credential, or a wrong one.
API_KEY_EXPIRED401The key is outside its validity dates.
IP_NOT_ALLOWED403The key is limited to other IP addresses.
ACCOUNT_INACTIVE403The account is not active.
FEATURE_NOT_ENABLED403The function is not enabled for your account: ask support.
CUSTOMER_OUT_OF_SCOPE403The customer is not in your network.
NOT_FOUND, SHIPMENT_NOT_FOUND, CUSTOMER_NOT_FOUND404It does not exist, or it is not yours.
OFFER_ALREADY_ORDERED409This offer was already bought with another idempotency key.
CUSTOMER_ALREADY_EXISTS, INVITATION_ALREADY_ACCEPTED409The customer or the invitation is already there.
IDEMPOTENCY_KEY_IN_USE409A call with this key is still running.
VERSION_RETIRED410The version you asked for is no longer served.
INSUFFICIENT_CREDIT422Your prepaid credit does not cover the amount.
SERVICE_NOT_AVAILABLE422A requested service is not available; details name the service and the carrier.
CARRIER_NOT_AVAILABLE422The carrier cannot be bought through the API.
IDEMPOTENCY_KEY_REUSED422The key was used with a different body.
DAILY_LIMIT_EXCEEDED, RATE_LIMIT_EXCEEDED429Too many requests. Wait for Retry-After.
SHIPMENT_CREATION_FAILED, CUSTOMER_CREATION_FAILED, SERVER_ERROR500Something failed on our side.
FEATURE_NOT_IMPLEMENTED501The operation is published but not built yet.
UPSTREAM_ERROR, UPSTREAM_TIMEOUT502, 504A system we depend on failed or was too slow.

What to retry

  • 400, 401, 403, 404, 409, 410 and 422 will not change if you send the same request again. Fix the request first.
  • 429: wait for the Retry-After header.
  • 500, 502, 503, 504: retry with growing delays. On a write, send the same Idempotency-Key: if the first try did go through you get its answer back, not a second purchase.

Was this page helpful?

Was this page helpful?