Errors

BeatAPI reports every failure with one of a fixed set of codes. The code is the part to branch on; the message is a sentence written for a person. Neither ever repeats what a model provider told us — no provider names, no provider status codes, no provider error text. Keep request_id for support.

Where a failure shows up

A task can fail at two points, and they look different:

When you create it. The request is refused before a task exists. You get an HTTP error with an error object and no data.id. Nothing is charged.
After it was accepted. POST returned 201 with data.id. The task later ends as status: "failed". GET /v1/tasks/{task_id} still answers 200; the failure is in data.error_code and data.error_message, and the credits reserved for the task are refunded.

{
  "error": {
    "code": "content_policy_violation",
    "message": "The request was blocked by content moderation. Please change the prompt or the input and try again.",
    "request_id": "req_abc123"
  }
}

{
  "data": {
    "id": "task_8K2qA",
    "status": "failed",
    "error_code": "content_policy_violation",
    "error_message": "The request was blocked by content moderation. Please change the prompt or the input and try again."
  }
}

The same failure carries the same code in both places, and in the error line of your usage log (content_policy_violation: The request was blocked…).

Codes

What happened	At create	On an accepted task	What to do
The prompt, an input, or the generated result was refused by content moderation	`400` `content_policy_violation`	`content_policy_violation`	Change the prompt or the input. Do not resend the same request.
A parameter is not accepted by this model (size, ratio, duration, count, prompt length…)	`400` `bad_request`	`bad_request`	Fix the field the message names. Retrying unchanged will fail again.
An input URL could not be downloaded, or the file could not be processed	`400` `bad_request`	`bad_request`	Use a publicly reachable HTTPS URL, or a supported format.
The API key is missing, invalid, or revoked	`401` `unauthorized`	—	Check the active key in the dashboard. A deleted key fails immediately.
The account balance is too low	`402` `insufficient_credits`	—	Add credits.
The account is not allowed this operation — for example a model that is not available on free credit	`403` `forbidden`	—	Read the message; for free-credit accounts, a top-up unlocks every model.
The idempotency key was reused with a different body	`409` `idempotency_conflict`	—	Reuse a key only for the identical request.
Your key sent too many requests, or too many of your tasks are running	`429` `rate_limit_exceeded` / `user_concurrency_exceeded`	—	Wait `retry_after_seconds`, or for a running task to finish.
The model is temporarily unavailable or at capacity on our side	`503` `processing_unavailable`	`processing_unavailable`	Retry later with backoff.
Generation did not finish in time	`504` `processing_timeout`	`processing_timeout`	Retry.
The result was generated but could not be stored	`502` `result_transfer_failed`	`result_transfer_failed`	Retry.
Generation failed for another reason on our side	`502` `processing_failed`	`processing_failed`	Retry.
Unexpected internal error	`500` `internal_error`	—	Retry once; if it persists, contact support with `request_id`.

processing_unavailable and rate_limit_exceeded are different things. rate_limit_exceeded is about your request rate and tells you to slow down. processing_unavailable says the model could not take work right now; your requests were fine.

Retry policy

Never retry unchanged: content_policy_violation, bad_request, unauthorized, forbidden, insufficient_credits, idempotency_conflict.
Retry after a wait: rate_limit_exceeded, user_concurrency_exceeded (honour retry_after_seconds when present), processing_unavailable.
Retry with backoff: processing_timeout, processing_failed, result_transfer_failed, internal_error. Use exponential backoff and a cap; a task that failed was refunded, so a new attempt is a new charge only if it succeeds.

Changes

2026-09-23 — A task that fails after acceptance because of a rejected parameter or an unreachable input now reports bad_request (it was processing_failed). A model provider’s own status code is no longer passed through at create: a moderation refusal is always 400 content_policy_violation, and a provider being unavailable is 503 processing_unavailable. A low balance at create is 402 insufficient_credits.