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

# Errors

> One envelope, machine-readable codes, and what to do about each.

Every error response has the same body:

```json theme={null}
{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "Input should be a valid string",
    "param": "source.url"
  }
}
```

| Field     | Meaning                                                      |
| --------- | ------------------------------------------------------------ |
| `type`    | The broad class — branch on this first.                      |
| `code`    | A stable machine-readable reason.                            |
| `message` | Human-readable. May change; don't parse it.                  |
| `param`   | The request field at fault, when there is one (dotted path). |

Every response also carries a `Request-Id` header (`req_…`). Include it when you contact support.

## Types

| `type`                  | HTTP          | Meaning                                                                                                             |
| ----------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------- |
| `invalid_request_error` | 400, 404, 409 | The request is malformed, refers to something that doesn't exist, or conflicts with current state. Fix the request. |
| `authentication_error`  | 401           | Bad or missing key — see [Authentication](/authentication).                                                         |
| `insufficient_credits`  | 402           | The balance can't cover the hold. Body includes `needed_cents` and `available_cents`.                               |
| `rate_limit_error`      | 429           | Slow down; honour `Retry-After`.                                                                                    |
| `api_error`             | 5xx           | Hooper's fault. Safe to retry with the same `Idempotency-Key`.                                                      |

## Codes you should handle

| `code`                                                      | HTTP | Where                    | What to do                                                                                              |
| ----------------------------------------------------------- | ---- | ------------------------ | ------------------------------------------------------------------------------------------------------- |
| `parameter_invalid`                                         | 400  | any                      | Check `param`.                                                                                          |
| `video_too_large`                                           | 400  | submit                   | The file is over 10 GB. Nothing was held; an uploaded blob was deleted.                                 |
| `upload_incomplete`                                         | 409  | submit (`upload` source) | The bytes haven't landed yet, or the object is empty — finish the `PUT`, then resubmit.                 |
| `organization_without_group`                                | 409  | submit                   | Your organization has no group linked yet; contact Hooper.                                              |
| `idempotency_key_reused`                                    | 400  | submit                   | Same `Idempotency-Key`, different body. Use a new key.                                                  |
| `idempotency_key_in_progress`                               | 409  | submit                   | A request with this `Idempotency-Key` is still being processed. Retry shortly; you'll get its response. |
| `insufficient_credits`                                      | 402  | submit                   | Top up, then resubmit.                                                                                  |
| `resource_missing`                                          | 404  | any `{id}`               | No such object for your organization.                                                                   |
| `missing_api_key` / `invalid_api_key` / `wrong_environment` | 401  | any                      | See [Authentication](/authentication).                                                                  |
| `rate_limit_exceeded`                                       | 429  | any                      | Back off for `Retry-After` seconds.                                                                     |

## Session failures

A session that fails does so asynchronously: `status` becomes `failed`, `error` is set, you receive a `session.failed` event, and **the hold is voided**. `error.code` values:

| `error.code`                            | Meaning                                                                       |
| --------------------------------------- | ----------------------------------------------------------------------------- |
| `no_hoops`                              | No hoop could be detected — check camera angle.                               |
| `no_court`                              | The court could not be detected.                                              |
| `no_shots`                              | The video contained no detectable shots.                                      |
| `video_too_large`                       | Over 1080p (or over 10 GB for a URL/Veo source). Uploaded bytes were deleted. |
| `source_invalid` / `source_unavailable` | The URL/Veo source was rejected or couldn't be downloaded.                    |
| `timeout`                               | Processing never reported back; swept after 24h.                              |
| `unknown`                               | Anything else. Quote the session id to support.                               |