Errors

There are two kinds of failure, and they look different:

The request is rejected. The API answers with a non-2xx status and an error body. Nothing was queued or charged.
A generation fails. It was accepted (202), ran, and ended with status failed and an error object. Failed generations aren't charged.

Request errors

Every error response has the same shape:

{
  "error": {
    "type": "invalid_request",
    "code": "invalid_parameters",
    "message": "Unsupported duration 7. Allowed: 5, 10",
    "param": "params.duration_seconds",
    "request_id": "req_b742b89c4fc9d7ece5d783ae"
  }
}

type is the broad category and decides the HTTP status. code is the specific reason. Both are stable, so branch on them, not on message, which is for people and may change. param names the offending field when there is one. Include request_id (also in the X-Request-Id header) when you contact support.

`type`	Status	Meaning	Retry?
`invalid_request`	400	The request is malformed or asks for something the model doesn't support.	No, fix it
`authentication`	401	Missing, malformed or revoked API key.	No
`insufficient_credits`	402	The balance can't cover the generation's maximum price.	After topping up
`permission`	403	The key lacks a scope, or the organization is suspended.	No
`not_found`	404	No such model, generation, upload or endpoint in your organization.	No
`conflict`	409	The request conflicts with current state.	Depends on `code`
`content_policy`	422	The prompt or a reference was refused before it ran.	No, change it
`rate_limit`	429	Too many requests, or too many generations in progress.	Yes, after `Retry-After`
`provider`	502	The model is unavailable right now (`model_unavailable`).	Yes, later
`internal`	500	Something went wrong on our side.	Yes, with backoff

Common codes:

`code`	Type	What to do
`invalid_parameters`	`invalid_request`	`param` says which field. The model page lists accepted values.
`invalid_request_body`	`invalid_request`	The JSON doesn't match the schema, e.g. an unknown field.
`feature_not_available`	`invalid_request`	`webhook_url` isn't available yet.
`upload_incomplete`, `upload_rejected`, `upload_expired`, `upload_not_found`	`invalid_request`	See Uploads.
`missing_scope`	`permission`	Use a key with the scope named in the message.
`idempotency_key_reused`	`conflict`	The key was used with a different request body. Use a new key.
`generation_finished`	`conflict`	You tried to cancel a generation that already finished.
`rate_limited`	`rate_limit`	Wait `Retry-After` seconds.
`concurrency_limit`	`rate_limit`	Wait for a running generation to finish.
`daily_spend_limit`	`rate_limit`	The organization reached its daily spending limit. It resets at 00:00 UTC (`Retry-After` says when); contact support to raise it. New organizations have a lower limit until their first payment is a day old.
`model_unavailable`	`provider`	Try again later, or use another model.

Generation errors

A failed generation's error has a code, a message, and retryable, which says whether sending the same request again might work.

`code`	Meaning	`retryable`
`content_rejected`	The provider or our checks refused the prompt, a reference or the output.	No
`invalid_parameters`	The provider rejected a value we passed on.	No
`provider_rate_limited`	The provider was overloaded, even after our retries.	Yes
`provider_unavailable`	The provider was down, even after our retries.	Yes
`quota_exhausted`	The provider's capacity for this model ran out.	Yes
`provider_timeout`	The provider didn't finish within the model's time limit.	No
`provider_internal_error`	The provider failed in a way we couldn't classify.	No
`internal_error`	We failed.	No

We retry temporary provider problems before failing a generation, so a retryable failure means the problem lasted a while. Wait a minute or more before retrying it.

In the SDKs

API errors raise RawFrameError with status, type, code, param and requestId / request_id. createAndWait and waitForCompletion raise GenerationFailedError, with the failed generation attached, when a generation fails or is canceled. Network failures raise APIConnectionError.

import { GenerationFailedError, RawFrame, RawFrameError } from "@rawframe/sdk";

const rf = new RawFrame();

try {
  await rf.generations.createAndWait({
    model: "bytedance/seedance-2.5",
    prompt: "A lighthouse in a storm",
    params: { duration_seconds: 7 }, // not a supported duration
  });
} catch (err) {
  if (err instanceof RawFrameError) {
    // The API rejected the request. Nothing was queued or charged.
    console.log(err.status, err.type, err.code, err.param, err.requestId);
    if (err.type === "insufficient_credits") {
      // Top up, or turn on auto-recharge, then retry.
    }
  } else if (err instanceof GenerationFailedError) {
    // The generation ran and failed. Failed generations aren't charged.
    const { code, retryable } = err.generation.error ?? {};
    console.log("failed:", code, retryable ? "(worth retrying)" : "");
  } else {
    throw err;
  }
}

Request errorsCopy Anchor Link

Generation errorsCopy Anchor Link

In the SDKsCopy Anchor Link

On this page

Request errors

Generation errors

In the SDKs