Find the next step when a request fails
| What you see | What to check |
|---|---|
401 / invalid credentials | Check the environment, header and key/account validity. Company keys have no timed expiry or refresh flow; replace a revoked key through your contact. In Authorize, paste the key alone. Do not send an expired portal session token. |
403 / forbidden | Authentication does not grant access to this operation or resource. Check the company linked to the key and the assignment ownership. Ask support to verify access; there is no OAuth scope string to add or token refresh that grants permission. |
429 / too many requests | Reduce request rate and concurrency. Honour Retry-After when supplied; otherwise use bounded backoff with jitter. See rate limits for the current quota status and retry guidance. |
400 / 422 · invalid request | Inspect the returned error details. Check required fields, enum values, address data and package units against the schema. Correct the input before retrying. |
404 / assignment not found | Use the returned assignment ID, not your external reference. Check the environment and the company associated with the API key. |
| Label not ready | Inspect assignment status and retrieve it again after a delay. If it remains unfinished, contact support with the assignment ID and request time. |
500 / 502 / 503 / 504 or timeout | Retry read requests with a bounded delay. For creation requests, check whether an assignment was already created before booking again. |
Read the error body
Application errors include statusCode, message, timestamp and path. message can be a string or a nested upstream error object; inspect any field-level details rather than matching one message string. Infrastructure errors can use a different format.
JSON · illustrative application error
{
"statusCode": 401,
"message": {
"message": "Unauthenticated."
},
"timestamp": "2026-01-01T12:00:00.000Z",
"path": "/health/auth"
}For help, send the endpoint, environment, request time, assignment ID if available and error details to support@21grams.com. Remove API keys and recipient details from shared diagnostics.
Ready to explore every field?
Open the interactive reference for request schemas and responses.