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
| Code | Type | Meaning |
|---|---|---|
| invalid_json | invalid_request_error | The request body is not valid JSON. |
| missing_parameter | invalid_request_error | A required parameter is missing.
|
| invalid_parameter | invalid_request_error | A parameter has an invalid value.
|
| unknown_parameter | invalid_request_error | The request has a parameter this endpoint doesn't accept.
|
| unknown_model | invalid_request_error | There is no model with that id. On create, estimate and regenerate. GET /models/{model} answers 404 not_found instead. |
| model_retired | invalid_request_error | That model has been retired.
|
| unknown_option | invalid_request_error | This model doesn't have that option.
|
| invalid_option | invalid_request_error | That option value isn't allowed for this model.
|
| invalid_input | invalid_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_input | invalid_request_error | This model needs an input that is missing. |
| too_many_inputs | invalid_request_error | Too many inputs for this model. |
| input_not_ready | invalid_request_error | That generation hasn't finished yet. A generation used as an input must have succeeded. |
| prompt_too_long | invalid_request_error | The prompt is too long for this model.
|
| invalid_cursor | invalid_request_error | The cursor isn't valid for this request. |
| invalid_date_range | invalid_request_error | The date range isn't valid. |
| invalid_idempotency_key | invalid_request_error | Idempotency-Key must be 1-255 printable ASCII characters. |
| api_key_in_url | invalid_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_regenerate | invalid_request_error | This generation can't be regenerated.
|
| not_a_video | invalid_request_error | Frames can only be taken from video outputs. |
| upload_empty | invalid_request_error | The upload is empty. |
| invalid_base64 | invalid_request_error | The upload data isn't valid base64. |
| invalid_webhook_url | invalid_request_error | That webhook URL isn't allowed. Website webhook management only. |
401 Unauthorized
| Code | Type | Meaning |
|---|---|---|
| missing_api_key | authentication_error | No API key was sent. Send it as Authorization: Bearer <key>. |
| invalid_api_key | authentication_error | This API key is not valid. |
| api_key_expired | authentication_error | This API key has expired. |
| api_key_revoked | authentication_error | This API key has been revoked. |
| not_signed_in | authentication_error | Please sign in. |
402 Payment required
| Code | Type | Meaning |
|---|---|---|
| insufficient_credits | billing_error | You don't have enough credits for this request.
|
| key_monthly_limit_reached | billing_error | This API key has reached its monthly credit limit.
|
403 Forbidden
| Code | Type | Meaning |
|---|---|---|
| insufficient_scope | permission_error | This API key doesn't have the permission this request needs.
|
| plan_required | permission_error | Your plan doesn't include this.
|
| account_banned | permission_error | This account is suspended. |
| api_not_enabled | permission_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_allowed | permission_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_required | permission_error | Please confirm it's you by signing in again. Website key management only: sign in again, then retry. |
| same_origin_required | permission_error | This request must come from the Craftful website as a JSON request. |
404 Not found
| Code | Type | Meaning |
|---|---|---|
| not_found | not_found_error | Not found. |
409 Conflict
| Code | Type | Meaning |
|---|---|---|
| key_limit_reached | conflict_error | You've reached your plan's limit of active API keys. Website key management only. |
| endpoint_limit_reached | conflict_error | You've reached your plan's limit of webhook endpoints. Website webhook management only. |
| endpoint_disabled | conflict_error | This webhook endpoint is disabled. Enable it first. Website webhook management only. Test events and resends need the endpoint enabled. |
| cannot_resend | conflict_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_progress | conflict_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_cancelable | conflict_error | This generation can't be canceled.
|
| voice_limit_reached | conflict_error | You've reached the limit of saved voices. |
| project_limit_reached | conflict_error | You've reached the limit of projects.
|
413 Too large
| Code | Type | Meaning |
|---|---|---|
| request_too_large | invalid_request_error | The request body is too large.
|
| file_too_large | invalid_request_error | The file is too large.
|
415 Unsupported type
| Code | Type | Meaning |
|---|---|---|
| unsupported_media_type | invalid_request_error | Send a JSON body with Content-Type: application/json.
|
| unsupported_file_type | invalid_request_error | This file type isn't supported.
|
422 Unprocessable
| Code | Type | Meaning |
|---|---|---|
| idempotency_key_reused | invalid_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_blocked | content_policy_error | This request was blocked by our content policy. You weren't charged.
|
429 Too many requests
| Code | Type | Meaning |
|---|---|---|
| rate_limited | rate_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_limited | rate_limit_error | Too many spending requests. Retry after the time in Retry-After. Retry after Retry-After. |
| frame_rate_limited | rate_limit_error | Too many frame requests. Retry after the time in Retry-After. Retry after Retry-After. |
| too_many_in_flight | rate_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_exceeded | rate_limit_error | You've reached today's upload limit. The plan's daily upload volume is used up. |
| too_many_auth_failures | rate_limit_error | Too many failed authentication attempts. Try again later. |
500 Server error
| Code | Type | Meaning |
|---|---|---|
| internal_error | api_error | Something went wrong on our side. |
503 Unavailable
| Code | Type | Meaning |
|---|---|---|
| upstream_unavailable | api_error | The generation service is temporarily unavailable. Retry shortly.
Also 502 when the service failed the call. |
| content_unverified | api_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_unavailable | api_error | The lyric writer is busy right now. You weren't charged.
|
504 Timeout
| Code | Type | Meaning |
|---|---|---|
| upstream_timeout | api_error | The generation service timed out. Retry shortly.
|
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.code | Meaning | Retryable |
|---|---|---|
| content_blocked | An input or the output was blocked by our content policy. You weren't charged. | no |
| content_unverified | Our content check couldn't run, so this generation didn't either. You weren't charged. Try again. | yes |
| provider_error | The model provider couldn't complete this generation. You weren't charged. | yes |
| provider_timeout | The model provider didn't finish in time. You weren't charged. | yes |
| provider_busy | The model provider was busy. You weren't charged. | yes |
| expired | This generation waited or ran too long and expired. You weren't charged. | yes |
| model_unavailable | This model was removed before the generation could run. You weren't charged. | no |
| account_banned | This account is suspended. You weren't charged. | no |
| internal_error | Something went wrong on our side. You weren't charged. | yes |