> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cherryshot.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> The error envelope, status codes, and error codes.

Errors return a consistent JSON envelope:

```json theme={null}
{
  "error": {
    "code": "insufficient_credits",
    "message": "This shoot needs 4 credits."
  }
}
```

Always branch on `error.code` (stable), not the human-readable `message` (may change).

## Status codes

| Status | Meaning                                           |
| ------ | ------------------------------------------------- |
| `200`  | Success.                                          |
| `201`  | Resource created (a shoot or video).              |
| `400`  | Validation error — check `message`.               |
| `401`  | Missing / invalid / revoked API key.              |
| `402`  | Insufficient credits.                             |
| `404`  | Resource not found (or not yours).                |
| `429`  | Rate limit exceeded (60 requests/min per key).    |
| `500`  | Something went wrong on our side — safe to retry. |

## Error codes

| `code`                 | When                                                 |
| ---------------------- | ---------------------------------------------------- |
| `unauthorized`         | No key, or an invalid/revoked key.                   |
| `rate_limited`         | Over the per-key rate limit.                         |
| `validation_error`     | A field is missing or invalid.                       |
| `insufficient_credits` | Not enough credits for the request.                  |
| `not_found`            | The id doesn't exist or isn't owned by your account. |
| `internal_error`       | Unexpected server error — retry with backoff.        |

<Note>
  For privacy and security, `500` responses return a generic message; the detail is logged
  server-side. If you hit a persistent `500`, share the request time and endpoint with support.
</Note>