HTTP Status Codes

Code	Meaning
200 / 201	Request succeeded / resource created
400	Validation or invalid state
401	Missing, invalid, expired, or wrong-purpose credential
402	Shipment access or an attempted billing payment requires merchant action
403	Authenticated but role/feature access is insufficient
404	Resource is absent within the authenticated tenant
409	A quota renewal is already processing for this billing period
429	Rate limit exceeded
500	Unexpected server error

Validation Shape

{
  "statusCode": 400,
  "message": ["email must be an email"],
  "error": "Bad Request"
}

Rate Limits

The default configured tiers are 120 requests per minute globally, 60 per minute for auth-tier traffic, and 30 per minute for public-tier traffic. Individual endpoints may be stricter: registration is 5/minute, login 10/minute, forgot-password 3/minute, token-based public tracking 30/minute, and legacy tracking-number lookup 15/minute.

Client Behavior

• Refresh once after a 401 caused by an expired access token; do not loop indefinitely.
• For SHIPMENT_ACCESS_BLOCKED, show the returned merchant action instead of retrying the carrier call.
• For BILLING_PAYMENT_REQUIRED, update the payment method and request a new renewal estimate.
• Respect Retry-After where present and use exponential backoff/jitter for 429 or transient 5xx responses.
• Do not retry validation, forbidden, conflict, or not-found responses without changing the request.
• Log the route, status, and safe correlation metadata without logging tokens, secrets, or customer PII.