Skip to content

Errors

Contents 26 pages

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.

The nine types#

Type Meaning Retry?
invalid_request Malformed or failed validation. Not until you change it.
authentication_error The credential is missing, unreadable, or no longer valid. No — fix the key.
permission_error The credential is valid but not allowed to do this. No. A fresh token will not help.
not_found No such thing, or it is not yours. No.
conflict Conflicts with current state. Re-read, then decide.
rate_limit A quota or rate limit. Yes, after Retry-After when it is sent. A spent daily quota resets at 00:00 UTC.
payment_error The card was refused, or the money could not move. Only after fixing the payment method.
upstream_error A carrier or processor failed us. A 503, yes, with backoff. A 502 payment_outcome_unknown, no — poll the booking.
api_error Our fault. Yes, with backoff. Never change your request in response to one.

Every code#

Authentication — the credential is the problem#

Code Status
missing_api_key 401 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.

Request shape#

Code Status
invalid_request 400 The request could not be understood.
invalid_body 400 The body is not valid JSON, or not a JSON object.
unsupported_content_type 415 Send Content-Type: application/json.
body_too_large 413 Over 1 MiB. Refused unread. Past 2 MiB the server refuses it before the API runs: still 413, with a plain-text body instead.
invalid_cursor 400 Pass next_cursor back verbatim; do not construct one.
invalid_parameter 400 A query parameter is not valid; message names it.
validation_failed 400 Some fields failed validation — including dimensions, weight or piece count out of range. See issues.
method_not_allowed 405 Wrong HTTP method for this path.
unknown_endpoint 404 No such endpoint. Check the path against the reference.
notification_email_required 400 An API booking has no signed-in person to email. Set a notification email on the organization, or a contact email on the key.

Freight and lanes#

Code Status
freight_invalid 400 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.

Resources#

Code Status
resource_not_found 404 No such resource, or it does not belong to this account. We do not distinguish the two — telling you which would leak whether an id exists.

Booking lifecycle#

Code Status
quote_expired 410 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.

Payment#

Code Status
payment_outcome_unknown 502 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.

Idempotency#

Code Status
idempotency_key_required 400 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.

Limits#

Code Status
rate_limit_exceeded 429 Too many requests in a short window. Wait Retry-After seconds, or a minute when it is absent. See rate limits.
daily_quota_exceeded 429 The daily quota for that operation — the organization's, or this key's own — is spent. Resets at 00:00 UTC.

Ours#

Code Status
upstream_unavailable 503 A carrier system is unreachable. Retry shortly.
internal_error 500 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.

Handling errors well#

Python
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 write
elif 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-Key
elif r.status_code == 409 and r.json()["error"]["code"] == "request_in_progress":
    # …retry shortly, same Idempotency-Key
elif not 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:

  1. Log request_id on every failure. It is the only thing that lets us find your exact call.
  2. 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.
  3. Reuse the Idempotency-Key when you retry a write. That is what makes the retry safe. See idempotency.

Refusals you can see#

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.