Errors and retries
34 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. 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.docs_urlurlA link to this code on this page.Every code
34 codes. Only one of them can mean you were charged, and it says so itself.
HTTPCode, meaning, what to doChargedRetry
400
invalid_paramsA parameter is invalidFix the parameter named in param. problems lists each one.NoAfter 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.NoNo404
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_failedThe data source failedRetry. With the same Idempotency-Key it can never be charged twice.NoYes502
upstream_changedThe data source returned an unexpected structureRetry later. The endpoint may pause itself until it is fixed; Status will say so.NoYes502
upstream_unclearThe data source's answer could not be interpreted; retry at most onceRetry once, then stop.NoOnce503
upstream_busyThe data source is busy; 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