Skip to Content

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

CodeWhat it meansWhat to doRetry
validation_failed400The 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
unauthorized401The key is missing, malformed, unknown, revoked or expired.Check the Authorization header, or create a new key in your account.No
forbidden403The 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_reached402Your 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_found404There 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_progress409Another call is creating the same article right now. details.retry is true.Send it again after a few seconds.Yes
not_ready409The 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_cancellable409The 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_conflict409The Idempotency-Key was already used with a different body within the last 24 hours.Use a new key for a new request.No
limit_reached409You 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_large413The request body is over 4 MB. details.maxBytes is the limit.Send images and 3D files as links, and split large batches.No
rate_limited429Too 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_error500Something 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.

On this page