Sociaro

Errors

Every status you can receive, what it means, and what to do. The /v2 routes answer in one envelope with an error.type: see /v2 errors.

status meaning what to do
400 The request was not understood — an unknown parameter, a value outside what the model accepts, or something you sent that we could not use, such as a reference image we could not download, or a user that is not a string of at most 128 characters with no control characters. Read the message; it names the field or the item. Retrying the same request unchanged will not help.
401 The key is missing, wrong, or revoked. Check the Authorization header. Keys start with sk-.
403 The key exists but may not reach this model, or your organisation does not have the feature switched on (Gateway.RealFacesNotEnabled). GET /v1/models shows what it may reach. For a feature, contact support.
404 No such job or file, or no such door. Check the id and the path. A job id belongs to the key that made it.
408 A request body did not arrive in time. Today that is a file upload to POST /v2/files that took longer than 10 minutes. Send the file again. Nothing was stored. See Files.
409 Your account is in a state that has to change before the call can work. Today that means one thing: your organisation has no spending limit configured, so there is no remainder to report. Retrying will not help and nothing is wrong with your request — contact your account manager.
413 A file is larger than the route accepts. On POST /v2/files the limit is 100,000,000 bytes. POST /v2/jobs/estimate takes a body of at most 2,097,152 bytes (request_too_large). Send a smaller file; for an estimate, send an inline data: file as a URL that serves the same file (the estimate reads it there; for a model priced on an input's length it measures that file). Resending it unchanged fails the same way.
415 A file sent to POST /v2/files is not accepted: its Content-Type is not an allowed one (unsupported_media_type), or its bytes are not what the Content-Type says (content_type_mismatch). Files lists the allowed types. Fix the type or the file; resending it unchanged fails the same way.
422 One of the media files you sent could not be prepared for the generator. The message names the file by its position among your media and its role, with the reason; provider_code carries the generator's code when it gave one. Replace or re-encode that file; resubmitting it unchanged fails the same way. Nothing was submitted or charged.
429 Out of balance, too many requests, or the generator is busy. The message says which. Out of balance and too many requests are OUR refusals, in our words; for balance, top up in the console. A busy generator's 429 comes with Retry-After and carries the generator's own words, and its code in provider_code, when it gave them (else the generator is at capacity, retry shortly): wait that many seconds and send it again.
500 An unexpected internal error. Retry. If it persists, tell us.
502 A vendor failed or could not be reached — except on GET /v1/balance, where no vendor is involved and a 502 means our own key check failed. When the generator said why, the message is its own words and provider_code its code. On a poll, retry — and if one vendor is down, another model often is not. On a submit, do not retry blindly: there is no idempotency key on these routes, so a 502 can equally mean the generator accepted your job and started charging for it while its id never reached us. Check whether a job appeared before sending the same request again. The same caution applies to a 503 on a submit.
503 Temporarily unavailable — usually a shared, rate-limited resource that is busy. Read the message. A refusal raised before anything was submitted says so, and is safe to retry as-is — reference-image preparation is the common one. Otherwise treat it like a 502 on a submit: check whether a job appeared first. When it carries Retry-After, wait that many seconds. On /v1/ideogram/generations, /v1/kling/generations, /v1/pixverse/generations, /v1/pruna/generations and /v1/sonilo/generations, a 503 with error.code Gateway.UpstreamUnavailable and no Retry-After is a refusal of the gateway, not of your request: nothing was created or charged — retry later.
504 The vendor took too long. For media, use the async door — it is built for slow work.

/v2 errors

Every error answer of every /v2 route (jobs, files, models, the estimate, the lookup, the OpenAPI document and any path beneath them), the gateway's own 400, 413, 429, 502 and 504 included, has the same error object (the one exception: a request the gateway cannot parse at all, such as a malformed request line or header line, gets a 400 that is a plain page, not JSON):

{"error": {"type": "invalid_input", "code": "invalid_input", "message": "model (string) is required", "provider_message": null},
 "job_created": false}
  • type is one of nine words. Switch on type; log code. Every code that existed before is unchanged, with one exception (a key's own rate limit on POST /v2/jobs is now rate_limit_exceeded; it was insufficient_budget), and type was added beside it.
  • message is a sentence written to be read. It names the field, never the value you sent.
  • provider_message is null on every submit error: no generator is called before a job exists. On a failed job it is the generator's own sentence where there is one, and the key is absent otherwise; see the Jobs API.
  • job_created appears only on the errors of POST /v2/jobs, at the top level, beside error. Other routes carry the same error object without it. A 404 or 405 for a wrong path or method under those routes also keeps the older detail key. A path that is not one of those routes at all (/v2/job/abc, a typo of /v2/jobs/abc) is not served by them, and its 404 is not in this envelope: check the path before you parse the body. Outside our control is an error page of the CDN in front of us, which is not JSON.
  • Extra keys of a 429 (scope, retry_after) and the Retry-After header are as before.
error.type error.code
invalid_input invalid_input, unsupported_input, invalid_idempotency_key, idempotency_key_required, invalid_callback_url, idempotency_conflict, cancel_not_supported, file_too_large, unsupported_media_type, content_type_mismatch, upload_timeout, estimate_unavailable, method_not_allowed, request_too_large
unauthorized invalid_key
forbidden forbidden
not_found model_not_found, job_not_found, file_not_found, not_found, route_not_found
insufficient_balance insufficient_budget
rate_limited rate_limit_exceeded, rate_limited
concurrency_limited too_many_inflight_jobs, too_many_uploads
upstream_error gateway_unavailable
internal_error unavailable, internal_error, upstream_error

Three kinds of 429. insufficient_balance (code insufficient_budget): your organisation's balance; top up in the console. rate_limited (code rate_limit_exceeded): the API key's own rate limit; wait for Retry-After. concurrency_limited (codes too_many_inflight_jobs, too_many_uploads): too many jobs or uploads in flight at once for the key or the organisation; Retry-After is set. A 429 whose cause we cannot classify is reported as insufficient_balance. The estimate route never answers insufficient_balance.

The estimate route (POST /v2/jobs/estimate) uses the codes above plus one of its own: estimate_unavailable (400, type invalid_input) means the price depends on the length of an input file and we could not read it; submitting is not affected. Its body takes the same fields as the submit's, up to 2,097,152 bytes (larger is 413, request_too_large: send inline data: files as URLs). Its 503 is unavailable, and none of its answers carries job_created. See the Jobs API.

Errors of the gateway itself. In front of the relay, nginx answers 400 (invalid_input, for a request body it cannot read or headers that are too large), 413 (request_too_large), 429 (rate_limited, for a caller with no valid key, with Retry-After: 5), and 502 and 504 (gateway_unavailable, type upstream_error) in the same envelope.

The gateway also caps the uploads it holds at once: only POST /v2/jobs and POST /v2/jobs/estimate can get that 429, typed concurrency_limited with code too_many_uploads (the same code as the Files API's), Retry-After: 5; no job was created and nothing was charged. Lookup, polling and cancel never get it: a body sent to any other route is refused 413 before it is read.

A failed job's error has a type too, by its code:

error.code error.type
provider_rejected invalid_input
provider_failed, timeout, expired, output_too_large, unsupported_media upstream_error
quota_exceeded forbidden
internal internal_error
canceled none: a cancel you asked for is not an error, so this is the one /v2 error without a type

provider_rejected has the type invalid_input, the same word a refusal at submit has. On a job object it means the job existed and was not charged. On a submit answer, job_created tells you whether a job exists.

job_created.

  • false: this attempt created nothing. Release the user's credits when no earlier attempt with the same Idempotency-Key ended ambiguously (null, 502, 503, 504, or no answer); see null below. On 409 idempotency_conflict it is false for this request, and the key already belongs to an earlier job with another body.
  • null: we cannot tell. This happens in three cases: a 503 after the job may have been stored, or after a timeout inside the submit's transaction (a wait on an earlier attempt with the same key), a 502 or 504 from the gateway, and a 500 internal_error, an unexpected internal error that may have come after the job was stored. An answer that is not JSON, or no answer at all, means the same. Hold the credits and send the same request again with the same Idempotency-Key: it returns the existing job or creates exactly one. You can also look the key up with GET /v2/jobs?idempotency_key= (Jobs API). A 404 from a lookup sent at least 180 seconds after your last attempt with that key ended (an answer arrived, the connection closed, or you stopped waiting and closed it) is final: no job exists, none of those attempts will create one, and you can release the credits. This holds for requests sent to the public API host, on the condition that a request reaches our server within 90 seconds after your attempt with that key ended; sending the same request again with the same Idempotency-Key is always safe and settles the outcome without relying on timing (it returns the existing job or creates exactly one). A 404 from a lookup sent before that is not proof, whenever it arrives, because an earlier attempt may still create the job; a 503 from the lookup is not an answer about the job either, so ask again. A refusal of a later attempt (a 401, 403, 429 or 503, for example) or its job_created: false settles only that attempt: keep the credits held until the answer is the job (200 or 202) or that 404. A job that does appear is charged once.
  • A success answer (202, or 200 for a repeated key) carries the job and no job_created.

Reading a refusal

Errors carry a message written to be read:

{"error": {"message": "budget exceeded for this organisation: its spend has reached the balance it was topped up to. Top up in the console to continue."}}

One exception, and it is the generator's doing. When a generator refuses a submission on the uncensored line — a bad parameter, an image it will not read — its own body is forwarded to you whole, in ITS shape rather than the envelope above, because its wording names the field and the limit and ours would only paraphrase. Names of the services and hosts behind the model are substituted out of it, and links and e-mail addresses in it become [link] and [email] (as in every generator sentence we pass on, outside /v1/byteplus/* and /v1/modelark, which pass the generator's words verbatim). So parse defensively on those routes: read error.message when it is there, and fall back to the HTTP status when the body is shaped some other way. A reference-free Alibaba twin on that line forwards no body: it answers in our envelope, a refusal as 502 with, as a rule, the generator's sentence in error.message and its code in error.provider_code when it sent them (some refusals carry only upstream auth failed or upstream submit failed and no provider_code), and a busy generator as 429 with Retry-After. When the generator's answer cannot be read at all, you get 503 with error.code Gateway.UpstreamUnavailable (the generator is unavailable to us; the same code and message as on the Seedance task routes), never an empty body. On a submit this 503 comes WITHOUT Retry-After: the outcome at the generator is unknown, so do not resubmit automatically. You hold no job id and are not charged for it.

A 401, 402, 403, 407 or 429 on that line (an Alibaba twin aside) whose body is only {"error": {"message": "the provider failed to complete this job"}}, with no Retry-After, is the generator's refusal, not a check of your key, grant or balance: keep the key, and do not retry it automatically. A /v2 job whose generator was still busy (429) on our last retry ends provider_failed with the generator's words and its provider_code. Any other 429 from the generator means it is busy: you get our 429 with Retry-After, in our envelope, with the generator's own sentence in error.message and its code in error.provider_code when it gave them (else the generator is at capacity, retry shortly). Wait that many seconds and send it again.

That substitution is specific to the uncensored line. The other two doors answer differently, and a client that applies the same parsing to them will be wrong: /v1/byteplus/* passes the generator's envelope through UNCHANGED, names included, and its error.code is the generator's vocabulary rather than ours — while OUR refusals on the Seedance task route carry an error.code of our own, always beginning Gateway. (Gateway.InsufficientBalance and Gateway.RateLimitExceeded are the two 429s), listed in full in the Generations API guide. One generator answer is NOT passed through there: when the request cannot be taken right now you get our 503 with error.code Gateway.UpstreamUnavailable, and a task that failed for that reason reads "status": "failed" with that same error. The Ideogram, Kling, PixVerse, Pruna and Sonilo routes (/v1/ideogram/generations, /v1/kling/generations, /v1/pixverse/generations, /v1/pruna/generations, /v1/sonilo/generations) answer a submit that cannot be taken right now the same way (503 Gateway.UpstreamUnavailable, no Retry-After, nothing created or charged) — except that on Ideogram the generator's 404, 405, 407, 409 or 415 answers 502 with submit failed upstream and nothing of the generator's — a request the generator refuses 400 with its own words and its code in provider_code (on Ideogram the generator's reject_reason for a refusal, failure_reason for a failed job), a busy generator 429 with Retry-After, and a generator that failed 502; that 429 and that 502 carry the generator's own words and its code in provider_code when it gave them. The Recraft route (/v1/recraft/generations) never passes the generator's answer back on a submit: every refusal by the generator, and a busy generator, arrives at the poll as status: "failed" with the generator's own words in error.message and its code in provider_code when it gave them, at no charge (on /v2/jobs the job ends provider_failed). Its submit answers 400 only for its own check of the body, and, besides out of balance and too many requests, 429 with Retry-After when the job cannot be taken right now: nothing was created or charged; wait that many seconds and send it again. The ModelArk-shaped route /v1/modelark answers like the Seedance task route, except that its submit returns at once with queued (and answers an out-of-balance key 402, not 429), and what could not be accepted or was refused by the generator arrives on the poll as status: "failed" with an error.code — among ours Gateway.InputUrlInvalid, Gateway.InputDownloadFailed, Gateway.InputPreparationFailed, Gateway.InputPreparationTimeout, Gateway.InputPreparationBusy and Gateway.ResultUnavailable, with the same meanings as on the routes below (see the Generations API guide); /v1/images/async (which serves no model at present) reports a failure through its webhook as { job_id, status, model } with no error object at all. On the routes that prepare reference files before submitting, a refusal raised while your files are prepared carries an error.code with the same names: Gateway.InputUrlInvalid, Gateway.InputDownloadFailed and Gateway.InvalidRequest (400), Gateway.InputPreparationFailed (422), and Gateway.InputPreparationBusy and Gateway.InputPreparationTimeout (503, with Retry-After). Gateway.InputPreparationFailed names the file — its role and its position among your media — and carries the generator's reason and, as provider_code, its code when it gave one: that file will fail the same way again. Busy and Timeout are temporary. A refusal raised while your files were being prepared is listed in your Logs as a failed request, at no charge.

We keep them plain on purpose. An error that says only "Bad Gateway" when the real cause is an empty balance costs an hour of looking for an outage that never happened — that has happened here, which is why these messages say what they mean.

What never happens silently

  • A refused request is never charged.
  • A failed generation is never charged, and still appears in your Logs. The one exception is an Ideogram job whose images were all withheld by the generator's safety check: it ends failed and is charged for the images generated.
  • A job that cannot be priced is withheld, not delivered free — so a missing charge is never the first sign that something went wrong.