Reference
Errors
Every error response follows the same shape. Here's how to interpret them.
Error response format
{
"error": {
"code": "invalid_service_level",
"message": "The service_level \"foo\" is not valid. See /api/reference/service-levels/.",
"field": "service_level",
"request_id": "req_5fa178c2083189b168663201"
}
}
HTTP status codes
| Code | Meaning | When you see it |
|---|---|---|
| 200 | OK | Successful GET / PATCH |
| 201 | Created | Successful POST that created a resource |
| 204 | No Content | Successful DELETE or no-content update |
| 400 | Bad Request | Invalid JSON, missing required fields, schema violation |
| 401 | Unauthorized | Missing, invalid, or expired token |
| 403 | Forbidden | Valid token but insufficient scope or attempting cross-shipper access |
| 404 | Not Found | Resource ID does not exist or is not in your scope |
| 409 | Conflict | Resource state prevents the operation (e.g. cancelling a delivered order) |
| 422 | Unprocessable Entity | Valid JSON but business-rule violation (e.g. invalid service_level) |
| 429 | Too Many Requests | Rate limit exceeded. See Rate Limits. |
| 500 | Internal Server Error | Unexpected server-side failure. Safe to retry with backoff. |
| 502 | Bad Gateway | Transient upstream issue. Retry with backoff. |
| 503 | Service Unavailable | Maintenance or overload. Retry with backoff. |
Common error codes
| error.code | HTTP | Meaning |
|---|---|---|
| invalid_credentials | 401 | Email/password incorrect on token request |
| token_expired | 401 | Use refresh_token to get a new access token |
| token_revoked | 401 | Token has been revoked. Re-authenticate. |
| missing_required_field | 400 | A required field was omitted. See error.field. |
| invalid_service_level | 422 | Service level code not recognized |
| invalid_zip | 422 | ZIP code not in coverage area |
| order_not_found | 404 | The order ID does not exist in your scope |
| order_already_cancelled | 409 | Cannot modify a cancelled order |
| rate_limit_exceeded | 429 | Too many requests. Back off and retry. |
Retry strategy
- Retry: 429, 500, 502, 503, 504 — use exponential backoff with jitter, max 5 attempts
- Don't retry: 400, 401, 403, 404, 409, 422 — the request itself is the problem
- Use the
request_idwhen contacting support. It's the fastest way to look up what happened.