Errors and retries

A refusal from the DataMind Platform API tells you what went wrong and whether sending the request again can succeed. This page lists the statuses and codes you can meet and the retry behaviour for each one; for your first request from scratch, see Use the API.

What an error looks like

Every error the platform itself produces uses the OpenAI error shape:

json

{
  "error": {
    "message": "Rate limit exceeded - retry in 42s",
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded"
  }
}

message says what happened, in one sentence.
type groups the error family: authentication_error, invalid_request_error, rate_limit_error, billing_error or api_error.
code is the value your retry logic acts on.

Most errors the platform itself decides carry a named code. An error relayed from a model provider, and some internal failures, keep the HTTP status number as code instead; a plain unexpected failure reads internal_error. Match on the status and the code together.

Errors by status

These are the statuses the API can answer with; the code column is what your retry logic reads.

Status	`code`	What it means	What to do
400	`invalid_request`	The body is not a valid JSON object, or a field is missing or not accepted. This covers a model outside your key's menu, a thinking effort the model does not support and an unknown `provider.sort` value.	Correct the request and send it again. The field-level refusals are on Chat completions.
400	`content_filter`	Your company blocks personal data transmission and the request contained some. The message reads `PII detected in request: <TYPE> (<count>), ... This company's policy prohibits PII transmission to upstream providers; the request was not forwarded.` It names the kinds of data and counts, never the values.	Remove the personal data and send the request again.
401	`invalid_api_key`	The `x-api-key` header is missing or empty, or the key was rotated or revoked. The message reads `Invalid or missing API key`.	Send your company's current key. An Administrator manages keys in Settings.
402	`budget_exceeded`	Extra spend reached the monthly spend cap.	An Administrator raises the cap in Settings, or wait for the next billing window. Retrying as-is cannot succeed.
402	`no_active_subscription`	The company has no active plan; the message asks you to contact your DataMind integrator.	An Administrator selects a plan on Pricing.
402	`standard_quota_exceeded`	The plan's Standard allowance is used up, and the plan prices no Standard overage.	Send the request to a pay-as-you-go model, or contact DataMind about a plan that prices Standard overage.
413	`PAYLOAD_TOO_LARGE`	The request body is larger than the platform allows; the refusal names the size limit.	Send a smaller request: fewer or smaller files, or a shorter conversation.
429	`rate_limit_exceeded`	Your company sent more requests this minute than its rate allows. The message reads `Rate limit exceeded - retry in <seconds>s`.	Wait the seconds in the `retry-after` header, then send the request again.
429	`concurrency_limit_exceeded`	Your company is running more requests at once than its limit allows: `Too many concurrent requests - wait for an in-flight request to finish`.	Wait for one of your running requests to finish (`retry-after` is `1`), then send it again.
500	`internal_error`	An unexpected failure on the DataMind side.	Retry with a short back-off; contact DataMind support if it repeats.
502	`upstream_unavailable`	The model provider could not be reached.	Retry with a short back-off, or choose another model.
503	`service_unavailable`	Part of the platform is briefly unavailable; the message says which part, in the four cases below.	Retry shortly.
504	`upstream_timeout`	The model provider did not answer in time.	Retry with a short back-off, or make the request smaller.

The 503 code covers four situations, and the message tells you which one you met:

Model catalog is unavailable: the model list cannot be read right now. Retry shortly.
Pricing for model "<model>" is temporarily unavailable - retry later or pick another model from GET /models: the model cannot be priced, so it is not served. Retry later, or pick another model.
The <provider> service is temporarily unavailable - retry shortly: the web search or web read service cannot serve the call. Retry shortly.
Account limits are unavailable - retry shortly: your company's limits cannot be checked, and a request that cannot be checked is not forwarded. Retry shortly.

Errors from the web tool endpoints

The web search and web read endpoints refuse a request in the same shape as a chat request:

A search without a query is refused with Search query is required (use 'q' or 'query' parameter).
A read without a URL is refused with 'url' is required.
When the tool service itself cannot serve the call, the answer is the 503 service_unavailable.

The endpoints and their parameters are described on Web search and web read.

Retrying a request

Tip

Retry 429, 500, 502, 503 and 504 with a short back-off. A 402 is a billing state: retrying does not help until the plan or the spend cap changes.

On a 429, wait the seconds in the retry-after header before sending the request again. For a rate refusal that is the time left in the current minute; for a concurrency refusal it is 1.
Money refusals answer 402 instead of 429, so SDK retry logic, which retries 429, leaves them alone: they stay until the plan or the spend cap changes.
Limits gate a request before it starts; they never cut off an answer that is already streaming.
A refusal still counts toward your requests-per-minute rate, so back off rather than retrying in a tight loop.
A request refused before it reached a model is not billed. Once a request reaches a model, you pay for what it produced: a stream that breaks, or that you close early, still bills the tokens generated so far.
If a stream broke after it started, its last event is event: error with the code stream_interrupted. Send the request again.

The limits that gate requests, and what happens when you reach them, are on Limits and the spend cap.

Questions, answered

Why do money limits return `402` and not `429`?

A 402 cannot be fixed by retrying: it stays until the plan or the spend cap changes. That is why it is a separate status from 429, so automatic retry logic leaves it alone.

Which errors should I retry?

Retry 429, 500, 502, 503 and 504 with a short back-off, and wait for retry-after on a 429. Do not retry 400, 401, 402 or 413 as they are: correct the request, the key, the plan or the size first.

How long should I wait after a 429?

Wait the seconds the retry-after header gives. For a rate refusal that is the time left in the current minute; for a concurrency refusal it is 1, and the refusal clears as soon as one of your running requests finishes.

Why does code sometimes hold a number instead of a name?

An error relayed from a model provider, and some internal failures, keep the HTTP status number as code. Branch on the named codes on this page; when code is a number, treat it as the status.

The error says service_unavailable. What actually broke?

The message names the part that is briefly unavailable: the model list, a model's pricing, the web tool service or your company's limits. In each case, retry shortly.

Should I match on code or on type?

On code. type groups the error family, such as rate_limit_error or billing_error; it helps you route logging but does not identify the exact problem.

Is a timed-out request safe to retry?

Yes. A 504 means the model provider did not answer in time; send the request again with a short back-off. Long answers time out first, so make the request smaller if it repeats.

What does a plain 500 mean?

An unexpected failure on the DataMind side; the request was not served. Retry with a short back-off, and contact DataMind support if it repeats.