# Errors

The API signals failures with standard HTTP status codes. Error responses carry a JSON
body describing what went wrong.

## Status codes

| Code | Meaning | What to do |
| --- | --- | --- |
| `200` / `201` | Success. `201` is returned when a resource was created. | Continue. |
| `400` | The request body failed validation — a missing required field, or a value outside the allowed enum. | Fix the payload. Retrying unchanged will fail again. |
| `401` | Missing, malformed, or expired bearer token. | Refresh the token and retry once. See [Authentication](/guides/authentication/). |
| `404` | The resource does not exist, or it exists but belongs to another account. | Do not retry. Re-check the identifier. |

## Error body

Error responses share one shape:

```json
{
  "error": "Human readable description of what failed"
}
```

Treat the message as diagnostic text for your logs, not as a stable machine-readable
code — branch on the HTTP status instead.

## Retry policy

Only `401` is worth retrying automatically, and only once, after refreshing credentials.
`400` and `404` are deterministic: the same request will always produce the same result.

For network-level failures and `5xx` responses, exponential backoff with jitter is
appropriate. Cap the total attempts — an operation like
[Schedule a pre-recorded live stream](/stream-scheduler/schedule-a-pre-recorded-live-stream/)
is not idempotent, so blind retries can create duplicate events.

## Operations that are not instantaneous

Some operations acknowledge the request before the work finishes:

- [End active scheduled stream](/stream-scheduler/end-active-scheduled-stream/) returns
  as soon as the stop is accepted. Playback and destination disconnects take a few
  seconds to settle.
- [Start a new video import](/video-imports/start-a-new-video-import/) is asynchronous.
  Poll [List queued video imports](/video-imports/list-queued-video-imports/); when the
  video ID is no longer in the queue, the import has finished and the asset appears in
  the VOD library.

Design around eventual consistency for these — a read immediately after the write may
still show the old state.