Error Codes

Vehicle API and Transportation & Cargo API errors use the same compact error object:

{
  "message": "Human-readable error message"
}

The HTTP status code carries the category of the failure.

Documented HTTP Status Codes

Status	Meaning	Typical cause	What to do
400	Invalid image or malformed request.	Missing image, unreadable image, unsupported image data, or request parameters that prevent recognition from starting.	Check the input image guide, request format and multipart field names.
401	Unauthorized.	Missing API key.	Send the API key in the x-api-key header.
403	Forbidden.	Invalid API key, disabled product access on the key, missing subscription/credit entitlement, or a key that belongs to another workspace.	Verify the key value, product toggles, workspace subscription and credit balance in Dashboard.
405	Method not allowed.	Calling a recognition endpoint with a method other than POST.	Use POST for recognition calls.
408	Timeout.	Recognition did not complete in time.	Try a smaller image, disable wide-range analysis, narrow the ROI or retry later.
413	Payload too large.	Uploaded image is larger than the API can process.	Resize or compress the input image before upload.
429	Limit exceeded or throttled.	Too many requests, exhausted credits or missing active entitlement.	Slow down requests, review subscription/credit state, or contact support if the limit is unexpected.
500	Internal server error.	Unexpected server-side failure.	Retry and include the response message and request time when contacting support.
503	Service unavailable.	Worker queue is full or no worker is currently available.	Retry with backoff.
504	Gateway timeout.	Upstream worker did not respond in time.	Retry with backoff; if repeated, reduce image complexity or contact support.

Billing Note

For Vehicle API calls, the API description states that only 200 and 400 responses are charged. Other failures are intended to signal access, capacity or transport problems rather than successful recognition work.

Troubleshooting Checklist

1. Confirm that the API key is copied exactly and is sent as x-api-key.
2. Check that the API key is enabled for the product you are calling.
3. Verify that the workspace has an active subscription or available Carmen credits for the selected product.
4. Review image size, format and quality.
5. For repeated 503 or 504 errors, retry with exponential backoff.