Developers

Errors

Every error is one JSON envelope. code is stable: branch on it. message is for people and may change; param names the field (dotted, like inputs.images[2]); details depends on the code; doc_url links here. Every response carries X-Request-Id: quote it to support.

{
  "error": {
    "type": "billing_error",
    "code": "insufficient_credits",
    "message": "You don't have enough credits for this request.",
    "param": null,
    "details": {
      "required": 270,
      "balance": 120
    },
    "request_id": "req_01JD2V7K8Q4M9N3X5B6C7D8E9F",
    "doc_url": "https://craftful.ai/developers/errors#insufficient_credits"
  }
}

400 Bad request

CodeTypeMeaning
invalid_jsoninvalid_request_error

The request body is not valid JSON.

missing_parameterinvalid_request_error

A required parameter is missing.

param names the field.

invalid_parameterinvalid_request_error

A parameter has an invalid value.

param names the field.

unknown_parameterinvalid_request_error

The request has a parameter this endpoint doesn't accept.

param names the field. Request bodies are strict, to catch typos.

unknown_modelinvalid_request_error

There is no model with that id.

On create, estimate and regenerate. GET /models/{model} answers 404 not_found instead.

model_retiredinvalid_request_error

That model has been retired.

details.replacement names the model to use instead.

unknown_optioninvalid_request_error

This model doesn't have that option.

details.allowed lists the model's options.

invalid_optioninvalid_request_error

That option value isn't allowed for this model.

details.allowed lists the allowed values.

invalid_inputinvalid_request_error

An input is not valid for this model.

Media refs must be your own upl_…, gen_<id> or gen_<id>#<n>, of the slot's kind. Raw URLs aren't accepted: upload the file first.

missing_inputinvalid_request_error

This model needs an input that is missing.

too_many_inputsinvalid_request_error

Too many inputs for this model.

input_not_readyinvalid_request_error

That generation hasn't finished yet.

A generation used as an input must have succeeded.

prompt_too_longinvalid_request_error

The prompt is too long for this model.

details.max_chars is the model's limit.

invalid_cursorinvalid_request_error

The cursor isn't valid for this request.

invalid_date_rangeinvalid_request_error

The date range isn't valid.

invalid_idempotency_keyinvalid_request_error

Idempotency-Key must be 1-255 printable ASCII characters.

api_key_in_urlinvalid_request_error

Never put an API key in the URL. Send it in the Authorization header, and rotate the key you just sent.

The key was sent in the URL. Rotate it now, and send keys only in the Authorization header.

cannot_regenerateinvalid_request_error

This generation can't be regenerated.

details.reason says why (for example unsupported_input).

not_a_videoinvalid_request_error

Frames can only be taken from video outputs.

upload_emptyinvalid_request_error

The upload is empty.

invalid_base64invalid_request_error

The upload data isn't valid base64.

invalid_webhook_urlinvalid_request_error

That webhook URL isn't allowed.

Website webhook management only. details.reason says why.

401 Unauthorized

CodeTypeMeaning
missing_api_keyauthentication_error

No API key was sent. Send it as Authorization: Bearer <key>.

invalid_api_keyauthentication_error

This API key is not valid.

api_key_expiredauthentication_error

This API key has expired.

api_key_revokedauthentication_error

This API key has been revoked.

not_signed_inauthentication_error

Please sign in.

402 Payment required

CodeTypeMeaning
insufficient_creditsbilling_error

You don't have enough credits for this request.

details.required and details.balance. Never carries Retry-After.

key_monthly_limit_reachedbilling_error

This API key has reached its monthly credit limit.

details.limit, details.used and details.required: this key's family's spend this UTC month.

403 Forbidden

CodeTypeMeaning
insufficient_scopepermission_error

This API key doesn't have the permission this request needs.

details.required_scope names the scope the key needs.

plan_requiredpermission_error

Your plan doesn't include this.

details.required_plans lists the plans that include it.

account_bannedpermission_error

This account is suspended.

api_not_enabledpermission_error

The Craftful API isn't enabled for this account yet.

The API is in early access and not yet enabled for this account.

browser_requests_not_allowedpermission_error

The Craftful API can't be called from a browser. Call it from a server, and keep your key secret.

Requests with an Origin header are refused. Call the API from a server and keep the key secret.

reauth_requiredpermission_error

Please confirm it's you by signing in again.

Website key management only: sign in again, then retry.

same_origin_requiredpermission_error

This request must come from the Craftful website as a JSON request.

404 Not found

CodeTypeMeaning
not_foundnot_found_error

Not found.

409 Conflict

CodeTypeMeaning
key_limit_reachedconflict_error

You've reached your plan's limit of active API keys.

Website key management only. details.max_keys is the plan's limit.

endpoint_limit_reachedconflict_error

You've reached your plan's limit of webhook endpoints.

Website webhook management only. details.max_endpoints is the plan's limit.

endpoint_disabledconflict_error

This webhook endpoint is disabled. Enable it first.

Website webhook management only. Test events and resends need the endpoint enabled.

cannot_resendconflict_error

This delivery can't be resent.

Website webhook management only. A test event can't be resent: send a new one.

idempotency_request_in_progressconflict_error

A request with this Idempotency-Key is still in progress. Retry shortly.

The first request with this key is still running: retry after Retry-After.

generation_not_cancelableconflict_error

This generation can't be canceled.

details.status is its status, or details.reason: "source" for website and Discord generations.

voice_limit_reachedconflict_error

You've reached the limit of saved voices.

project_limit_reachedconflict_error

You've reached the limit of projects.

details.max_projects is the limit. Delete a project you no longer need to make room.

413 Too large

CodeTypeMeaning
request_too_largeinvalid_request_error

The request body is too large.

details.max_bytes.

file_too_largeinvalid_request_error

The file is too large.

details.max_bytes.

415 Unsupported type

CodeTypeMeaning
unsupported_media_typeinvalid_request_error

Send a JSON body with Content-Type: application/json.

details.allowed lists the content types.

unsupported_file_typeinvalid_request_error

This file type isn't supported.

details.allowed lists the file types. The type is read from the bytes.

422 Unprocessable

CodeTypeMeaning
idempotency_key_reusedinvalid_request_error

This Idempotency-Key was already used with a different request.

The same Idempotency-Key was sent with a different request (method, path or body). Use a new key per request.

content_blockedcontent_policy_error

This request was blocked by our content policy. You weren't charged.

details.category. Nothing was charged and nothing was created.

429 Too many requests

CodeTypeMeaning
rate_limitedrate_limit_error

Too many requests. Retry after the time in Retry-After.

Retry after Retry-After. Limits are per account; every key shares them.

spend_rate_limitedrate_limit_error

Too many spending requests. Retry after the time in Retry-After.

Retry after Retry-After.

frame_rate_limitedrate_limit_error

Too many frame requests. Retry after the time in Retry-After.

Retry after Retry-After.

too_many_in_flightrate_limit_error

Too many generations are queued or running. Wait for some to finish.

Too many generations queued or running (all sources). Retry-After: 10.

upload_quota_exceededrate_limit_error

You've reached today's upload limit.

The plan's daily upload volume is used up.

too_many_auth_failuresrate_limit_error

Too many failed authentication attempts. Try again later.

500 Server error

CodeTypeMeaning
internal_errorapi_error

Something went wrong on our side.

503 Unavailable

CodeTypeMeaning
upstream_unavailableapi_error

The generation service is temporarily unavailable. Retry shortly.

details.retryable: true. A 503 carries Retry-After; retrying with the same Idempotency-Key is safe.

Also 502 when the service failed the call.

content_unverifiedapi_error

Our content check couldn't run, so nothing was created. You weren't charged. Retry shortly.

Our content check couldn't run (for example, the classifier was briefly unavailable). Nothing was charged; retry after Retry-After.

lyrics_unavailableapi_error

The lyric writer is busy right now. You weren't charged.

details.refunded: true: the credits are back. Retry after Retry-After.

504 Timeout

CodeTypeMeaning
upstream_timeoutapi_error

The generation service timed out. Retry shortly.

details.retryable: true. Retry with the same Idempotency-Key: it can't create a second generation.

Generation failures

A generation that fails after it was accepted isn't an HTTP error: it ends with status: "failed" and an error object, and its credits are refunded in full. retryable says whether trying again may work.

error.codeMeaningRetryable
content_blockedAn input or the output was blocked by our content policy. You weren't charged.no
content_unverifiedOur content check couldn't run, so this generation didn't either. You weren't charged. Try again.yes
provider_errorThe model provider couldn't complete this generation. You weren't charged.yes
provider_timeoutThe model provider didn't finish in time. You weren't charged.yes
provider_busyThe model provider was busy. You weren't charged.yes
expiredThis generation waited or ran too long and expired. You weren't charged.yes
model_unavailableThis model was removed before the generation could run. You weren't charged.no
account_bannedThis account is suspended. You weren't charged.no
internal_errorSomething went wrong on our side. You weren't charged.yes