Troubleshooting

Error Codes & HTTP Responses

Standard error response payload structures and troubleshooting guidance for API v1.

Standard Error Format

All API error responses return standard JSON with an error object containing a machine-readable code and human-readable message:

          JSON
          Standard Error Structure
        

{
  "error": {
    "code": "plan_quota_exceeded",
    "message": "Period lookup quota reached. Contact billing to extend or upgrade."
  }
}

HTTP Status	Error Code	Description & Recommended Action
`400 Bad Request`	`unsupported_carrier`	The carrier slug provided is not in our allowlist. Check Supported Carriers.
`400 Bad Request`	`invalid_awb`	Tracking number (AWB) is empty or less than 8 characters long.
`401 Unauthorized`	`missing_api_key`	`X-API-Key` header is missing from request.
`401 Unauthorized`	`invalid_api_key`	API key provided is invalid, suspended, or revoked.
`402 Payment Required`	`payment_required`	Prepaid plan period has expired. Visit Pricing or contact billing to renew.
`403 Forbidden`	`carrier_not_allowed`	API key is restricted from querying this specific carrier.
`404 Not Found`	`shipment_not_found`	No tracking record found with the logistics partner for this consignment number.
`429 Too Many Requests`	`plan_quota_exceeded`	Included lookups for active prepaid period have been exhausted. Check Rate Limits.
`429 Too Many Requests`	`rate_limit_exceeded`	Per-second burst rate exceeded. Back off requests using jittered exponential backoff.
`429 Too Many Requests`	`daily_quota_exceeded`	Safety ceiling for daily queries exceeded. Contact support to request enterprise threshold adjustment.
`502 Bad Gateway`	`upstream_error`	Logistics network temporary outage with no cached data available. Retry request after a short interval.