Errors and retries
32 error codes share one structure: each says whether you were charged, whether to retry and what to change. An error costs $0.00, with 1 exception that says so itself: settlement_unknown.
What an error looks like
The same structure from every endpoint, and from requests that never reached one.
{
"code": "insufficient_balance",
"request_id": "8199dc1a-af29-4911-80c8-437718bfa8fb",
"message": "The balance is too low",
"message_zh": "余额不足",
"charged": false,
"retry": "after_fix",
"required": "0.002",
"available": "0.0009",
"docs_url": "https://dataxapi.com/docs/errors#insufficient_balance"
}The fields
The first six are always there. The rest appear when they have something to say.
Always there
codestringThe stable code. Branch on this, never on the message.request_idstringNames this request. Also in the X-Request-Id header. Quote it when you write to us.messagestringOne sentence in English, taken from the table below.message_zhstringThe same sentence in Chinese.chargedboolean | nullfalse: nothing was charged. true: the endpoint's price was charged; amount says how much. null: not known, which only settlement_unknown returns. Never read null as free.retrystringno, yes, once, after_fix (change the request first) or same_key (only with the same Idempotency-Key).When they apply
retry_after_secondsintegerHow long to wait. The same number as the Retry-After header.paramstringThe parameter that is wrong.problemsarrayEach thing wrong with the parameters, one by one.reasonstringWhich case of the code this is: does not exist or is private; rate or concurrency; a key's daily, monthly or total limit.requiredstringWhat the call needs, in US dollars.availablestringWhat the balance or the key's limit has left.amountstringWhat was charged, in US dollars, where charged is true.alternativeobjectWhen the call failed (upstream_failed, upstream_busy, timeout, capability_paused) and the endpoint has a backup version that can take calls: its capability, its path, its price (and per), and note and note_zh, a sentence saying the same. The backup takes the same parameters and returns the same fields, at its own price. Send it the same request with a new Idempotency-Key. Never given for a request that is wrong or an object that is not there.docs_urlurlA link to this code on this page.Every code
32 codes. Each error says whether it was charged, in `charged`.
HTTPCode, meaning, what to doChargedRetry
400
invalid_paramsA parameter is invalidFix the parameter named in param. problems lists each one.As charged saysAfter a fix400
request_not_servedThis combination of parameters cannot be served at presentDrop or change one parameter. The endpoint's page lists the combinations that work.NoAfter a fix400
max_price_exceededThe most this call could cost is above the limit you setRaise X-Max-Price or leave it out. required says what the call can cost.NoAfter a fix400
cursor_invalidThe cursor does not existSend next_cursor exactly as it came back, or start from the first page.NoNo400
cursor_mismatchThe cursor was issued for another endpoint or other parametersUse the cursor with the same endpoint and the same parameters that produced it.NoAfter a fix401
unauthorizedNo credential was sent, or it is invalid, disabled or expiredSend Authorization: Bearer with your key, and check in the Console that the key is active.NoNo402
insufficient_balanceThe balance is too lowTop up. required and available give the two amounts.NoAfter a fix402
key_budget_exceededThis key's spending limit does not cover the callRaise the key's limit in the Console or use another key. reason says daily, monthly or total.NoAfter a fix402
run_budget_exceededThis run's amount or call limit does not cover the callStart a new run with a larger budget. A run's budget cannot be raised.NoNo403
account_suspendedThe account is suspendedWrite to us. Calls will not work until it is lifted.NoNo403
forbiddenThis credential may not use that optionRemove the header this credential is not allowed to send.NoNo403
key_scope_deniedThis key may not call this endpointAdd the endpoint to the key's scope in the Console, or use a key that has it.NoNo404
not_foundThe object does not exist, is private or was deletedNothing to retry. reason says whether it does not exist or is private or deleted.As charged saysNo404
result_not_foundNo result under this request IDCheck the request ID. A call that was released has no result to read.NoNo404
run_not_foundNo run under this run IDCheck the run ID.NoNo404
unknown_endpointThere is no such endpointCheck the path against the API reference. A path is the endpoint ID with the dots turned into slashes. An old path says where it went in moved_to.NoNo409
call_in_progressThe call under this idempotency key is still running; ask again with the same key shortlyWait a moment, then send the same request with the same Idempotency-Key.NoWith the same idempotency key409
idempotency_conflictThis idempotency key was used for a different requestUse a new key for a new request.NoAfter a fix410
cursor_expiredThe cursor expired; start again from the first pageStart again from the first page. page.cursor_expires_at tells you in advance.NoNo410
result_expiredResults are kept for 24 hours; this one is goneMake the call again. It is a new call and is charged as one.NoNo410
run_expiredThis run has expired and starts no more callsStart a new run.NoNo429
rate_limitedToo many requests, or too many calls in progressWait retry_after_seconds when it is given. Without it, let one of your running calls finish.NoYes429
cost_cap_exceededThis account's allowance for today is used upWait until the time in Retry-After.NoYes429
uncharged_cost_limitToo many of this account's calls today returned nothing and were not charged; endpoints of this kind can be called again tomorrow (UTC)Wait until tomorrow (UTC); Retry-After gives the time. The limit is only on calls that return nothing and are not charged.NoYes500
settlement_unknownWhether this call settled is not known; ask again with the same idempotency key, or look it up by request IDDo not assume it was free. Send the same request with the same Idempotency-Key, or look the call up by its request ID.UnknownWith the same idempotency key500
internal_errorThe service failedRetry. The amount held for the call has been released.NoYes502
upstream_failedNo result came back this time and nothing was charged; retry shortlyRetry as retry says: usually yes; once when the service has already tried several times or the answer could not be read, with retry_after_seconds; no when retrying would be paid for again. If the same item keeps failing, it most likely cannot be retrieved. With the same Idempotency-Key it can never be charged twice.NoYes503
upstream_busyBusy just now; retry shortlyWait retry_after_seconds, then retry.NoYes503
capability_pausedThis endpoint is pausedCheck Status. Retry once the endpoint is back.NoYes503
overloadedThe service is busy; retry shortlyWait a few seconds and retry.NoYes504
timeoutThe data did not arrive in time; retry with the same idempotency keyRetry with the same Idempotency-Key.NoYes