Errors & status codes
Use internal_error_code to distinguish failures that share an HTTP status. For example, a 403 can indicate a missing scope, an IP restriction, or the wrong market.
| CODE | HTTP | MEANING & NEXT STEP |
|---|---|---|
R001 | 200 | Success The request completed successfully. |
R002 | 400 | Malformed request Check the named field for an unknown parameter, incorrect type, or out-of-range value. |
R003 | 404 | No such resource The resource does not exist or cannot be returned. A bid may be missing, expired, yours, or malformed. |
R004 | 405 | Wrong method Check the Allow response header. |
R005 | 404 | Unsupported version Use the /api/v1 base path. |
R006 | 409 | Duplicate still running Retry the identical request with the same reference. Reserved for future writes. |
R000 | 500 | Server error Quote the request_id when contacting Cru. |
A001 | 401 | Bad credentials Check both CLIENT-KEY and CLIENT-SECRET. |
A002 | 403 | Credential not usable The credential may be suspended or expired, or API access is disabled for the account. |
A003 | 403 | Missing scope Check required_scope in the error. Contact Cru if access is needed. |
A005 | 403 | Address not allowed The calling IP is not on the credential’s allowlist. |
A007 | 403 | HTTPS required Use an HTTPS base URL. |
A008 | 503 | Temporarily unavailable Back off and retry. |
A009 | 403 | Wrong market Compare store and allowed_stores. Use a permitted market hostname. |
What to do when a call fails
6 STEPSYour server
Read internal_error_code, not the HTTP status
The status tells you the category; the code tells you the cause. Branch on internal_error_code — A001, A003, A005, A009 all arrive as 401 or 403 and need different fixes.
KEEP
internal_error_code, request_idYour server
401 A001 — the credentials themselves
Both headers are checked together. Confirm CLIENT-KEY and CLIENT-SECRET are the pair Cru issued, and that neither picked up whitespace or a line break when it was copied.
Your server
403 — permitted, but not for this
A003 names the scope you are missing in required_scope. A009 means the hostname is a market this credential may not use — compare store with allowed_stores. A005 means the calling IP is not on the allowlist. A002 means the credential is suspended or expired.
Your server
400 R002 — the request
An unknown or malformed parameter is rejected rather than ignored, so a misspelling fails the whole call. The response names the field.
Your server
404 R003 — the bid is gone
Missing, expired, already filled, your own, or malformed all return the same answer. Treat it as "this bid is no longer available" and go back to the book.
Your server
503 A008 and 500 R000 — back off
Retry A008 with exponential backoff. R000 is Cru’s to fix: quote api_info.request_id, which is also returned as the X-Request-Id header.
KEEP
request_id
Include the request ID, endpoint, HTTP status, and internal error code. Do not include your client secret.