Every error the API sends has the same envelope. The one exception is a body
over 2 MiB: see body_too_large.
JSON
{"error":{"type":"invalid_request","code":"validation_failed","message":"Some fields did not pass validation. See `issues`.","issues":[{"field":"handling_units[0].length","code":"freight.length.too_large","message":"Max 600 in."}],"request_id":"req_3f9c2a71d04b8e65","doc_url":"/developers/errors#validation_failed"}}
type is the coarse class. Branch on it when you do not want to know
every code.
code is the exact reason. Branch on it when you do. Codes are stable —
we add them, we do not repurpose them.
message is written for a human reading a log. Do not parse it; it can
change.
issues appears only where a validator produced field-level detail.
Each issue has field, code and message. field points into your request
body, e.g. handling_units[0].length.
booking_id appears only on a booking refusal that is about an existing
booking — payment_outcome_unknown, quote_already_booked,
booking_already_paid — or that declined one (card_declined), so its
booking.declined webhook can be matched. Read it with
GET /bookings/{booking_id}.
fix_url appears when a person can fix the refusal in the web app — a
card to enable for API bookings, the terms to accept, a notification email to
set, White Glove to request. It is an absolute link to that page: open it, or
hand it to the person you act for.
new_amount_usd appears on price_changed: what the booking would charge
now, as a two-place string. Show it and ask before booking again.
request_id identifies this call in our logs. It is also on the
ShipEasy-Request-Id response header, including on success.
doc_url links to this page, at the anchor for the code. It is a path,
/developers/errors#<code>, on the host you called.
No API key was supplied. Send Authorization: Bearer se_live_….
invalid_api_key
401
Not a valid key. Check for a truncated copy-paste.
api_key_mode_mismatch
401
A test key against live data, or the reverse.
api_key_expired
401
Past its expiry. Create a new one; an AI app renews its own token.
api_key_revoked
401
Revoked, or an AI app disconnected. Make or connect a new one.
api_key_rotated
401
Rotated, and the overlap window has ended. Switch to the replacement.
Permission — the credential is fine, the answer is no#
Code
Status
api_key_disabled
403
ShipEasy disabled this key. It cannot be re-enabled from the web app — email support@shipeasyco.com.
api_disabled_for_organization
403
API access is not enabled for this account.
organization_inactive
403
This organization is not active.
insufficient_scope
403
This key does not carry the scope the endpoint requires.
shopify_stores_only
403
Only a Shopify store's key can use this endpoint: it reads that store's own Shopify orders. See Shopify stores.
not_available_for_shopify
403
A Shopify store's key cannot use this endpoint: it would return a buyer's name or address, or it belongs to the web app. See Shopify stores.
no_carrier_enabled
403
No carrier is enabled for this account, so there is nothing to rate with.
white_glove_not_approved
403
Not approved for White Glove service. Request access in the web app.
terms_not_accepted
403
Someone with authority must accept the current terms (in the web app, or for a Shopify store in its ShipEasy app) before anything can be booked.
billing_paused
403
Billing is paused for this account.
booking_not_allowed
403
An account setting prevents this booking; message says which.
booking_amount_exceeds_key_limit
403
The booking costs more than this key may spend per booking (booking.max_amount_usd on GET /account). ShipEasy sets that ceiling — email support@shipeasyco.com to change it.
The freight or lane cannot be rated as sent — for instance a ZIP that is not in its state. message says what. Out-of-range dimensions, weight or piece count return validation_failed instead.
origin_not_serviceable
400
Our carriers do not pick up from that origin.
destination_not_serviceable
400
Our carriers do not deliver to that destination.
no_rates_available
422
Every carrier declined to rate the lane. Check the ZIPs, or try another pickup date.
Rates have a shelf life. Re-quote and book the new rate.
quote_already_booked
409
That quote has already been booked, a booking for it is still settling, or one is waiting on the cardholder's bank. booking_id, when present, is the one to poll.
booking_already_paid
409
Paid but not yet booked. Poll the existing booking (booking_id) rather than paying again.
price_changed
409
The carrier's price moved since the quote was issued. We refuse rather than charge a different amount than you were quoted.
shipment_not_cancellable
409
Not cancellable from here: picked up, delivered, already cancelled or with a cancellation already requested — or no such shipment in this organization.
insurance_unavailable
409
Cargo coverage cannot be bought right now. Book without insurance, or check insurance.available on GET /account and try later. Nothing was charged.
The card may or may not have been charged. Do not book the quote again. Poll GET /bookings/{booking_id} — the id is on the error. A retry with the same Idempotency-Key replays this answer rather than charging again; if the booking has not settled in a few minutes, contact support.
card_declined
402
The card was declined. Nothing was charged and nothing was booked. message gives the issuer's reason; booking_id names the declined booking.
card_not_available
402
That card is not available to this organization.
card_not_enabled_for_api
402
The card exists but has not been authorized for unattended charges. See payment methods.
authentication_required
402
Not currently returned. When the bank wants the cardholder, POST /bookings answers 202 with status: "requires_authentication"; open its authenticate_url.
This endpoint requires an Idempotency-Key header — or the header was sent empty or longer than 255 characters.
idempotency_key_reuse
409
That key was already used with a different body or path. Use a new key for a new request.
request_in_progress
409
A request with that key is still in flight. Retry shortly with the same key — do not send a new one. If it persists, the first attempt died: it frees itself after 10 minutes, or after 24 hours if it had already charged — contact support with the request_id.
Something went wrong on our side. Quote the request_id.
api_unavailable
503
The API, or that part of it, is not available right now — for instance card bookings while they are paused, or a call we could not count against your usage. Retry after Retry-After.
r = session.post(url, json=body, headers=headers, timeout=30)
if r.status_code == 429:
time.sleep(int(r.headers.get("Retry-After", "60")))
# …retry, with the SAME Idempotency-Key if this was a writeelif r.status_code == 502:
# payment_outcome_unknown: do NOT retry. Poll the booking until it settles.
booking_id = r.json()["error"]["booking_id"]
# …GET /bookings/{booking_id}elif r.status_code >= 500:
# …retry with backoff, same Idempotency-Keyelif r.status_code == 409and r.json()["error"]["code"] == "request_in_progress":
# …retry shortly, same Idempotency-Keyelifnot r.ok:
err = r.json()["error"]
log.error("shipeasy %s: %s (request_id=%s)",
err["code"], err["message"], err["request_id"])
raise ShipEasyError(err["code"])
Three rules worth following:
Log request_id on every failure. It is the only thing that lets us find
your exact call.
Retry 429, 500 and 503, and a 409 request_in_progress — nothing else.
Any other 4xx will fail the same way however many times you send it. On a 502
payment_outcome_unknown, poll GET /bookings/{booking_id} instead.
Reuse the Idempotency-Key when you retry a write. That is what makes the
retry safe. See idempotency.
ShipEasy counts every refusal it sends a key: by key, by code and by day,
over the REST API and MCP alike. Your organization's owners and admins see the
counts in the web app, and a Shopify store sees its own in the ShipEasy app in
Shopify admin, under AI & API → Usage & problems, with the words for each
code and a Fix this link where a setting in your account is the cause.
Counted: every refusal sent after the key's secret checks out, including a
revoked or expired key, a spent daily quota and an AI app's tool refusal. Not
counted: a missing, malformed or unknown key, a wrong secret (so nobody who knows
only a key id can add to your counts), the per-minute burst limit, and a replayed
Idempotency-Key answer. Only the code and the count are kept, for 90 days —
never the request or anything in it.