Errors
The shape of an error answer, every error code, and which errors are safe to retry.
Every error answers with a body of this shape. Build your logic on error.code; the HTTP status tells you the kind of problem, and message is a sentence for people. details is there when we have more to say.
{
"error": {
"code": "validation_failed",
"message": "The product is not valid. See details.issues.",
"details": {
"issues": [{ "path": "dimensionsCm.w", "message": "Must be greater than 0" }]
}
}
}Error codes
| Code | What it means | What to do | Retry |
|---|---|---|---|
| validation_failed400 | The body is not JSON, a field is missing or not valid (details.issues lists each one with its path), a batch is empty or over the limit, or a query value is not valid. | Fix the request. Sending it again unchanged fails the same way. | No |
| unauthorized401 | The key is missing, malformed, unknown, revoked or expired. | Check the Authorization header, or create a new key in your account. | No |
| forbidden403 | The key is valid but may not make this call. details.reason is client_not_enabled (the API is not switched on for your company yet) or missing_scope (details.scope names the scope the key lacks). | Ask your CharpstAR contact to switch the API on, or use a key with that scope. | No |
| allowance_reached402 | Your allowance for this kind of work is used up for the period. details gives kind (a usage kind such as model_ordered or model_replaced, or models_in_contract when the contract's number of models would be passed), used, allowance, period and resetsAt. GET /api/v1/account shows the same numbers. | Wait for the period to reset, or ask your CharpstAR contact to raise the allowance. | No |
| not_found404 | There is no such article, order, job, import, configurator or subscription in your account, or the API is switched off. | Check the id or article number. Send the product first if it is new. | No |
| in_progress409 | Another call is creating the same article right now. details.retry is true. | Send it again after a few seconds. | Yes |
| not_ready409 | The thing is not in a state for this call yet: a model not waiting for your review, a delivered model (changes are requested in your account for now), a product with variations (reviewed in your account), an import that has not finished, or a job's product without a delivered model. details.status says where it is. | Read the product, import or job again and retry when details.status allows it. | No |
| not_cancellable409 | The product cannot be cancelled: modelling has started for it or one of its variations. details.status is its status and details.articleId the article that has started. | Talk to your CharpstAR contact. | No |
| idempotency_conflict409 | The Idempotency-Key was already used with a different body within the last 24 hours. | Use a new key for a new request. | No |
| limit_reached409 | You already have the maximum number of active event subscriptions. details.max is the limit. | Stop one you no longer use, then subscribe again. | No |
| too_large413 | The request body is over 4 MB. details.maxBytes is the limit. | Send images and 3D files as links, and split large batches. | No |
| rate_limited429 | Too many calls this minute (details.retryAfter, in seconds), or the key's daily limit is used up (details.reason is daily_quota, details.quota is the limit). | Wait for the Retry-After header, then try again. | Yes |
| internal_error500 | Something went wrong on our side. details.requestId identifies the call. | Retry with backoff. If it keeps happening, send us the requestId. | Yes |
Retrying
- Safe to retry: the errors with Yes under "Send again?" in the table. Use exponential backoff and honour
Retry-After. - Do not retry unchanged: any other error. It will fail the same way.