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

# Error handling

> Handle Videobase API failures and the current HTTP error contract.

Successful operations return HTTP `200`. The current v1 backend returns HTTP `500` for all application-level failures, including invalid authentication, validation errors, missing resources, rate limits, and unavailable features.

```json theme={null}
{
  "message": "File not found",
  "status": 500
}
```

<Warning>
  Do not interpret every `500` as a transient server outage. Read `message` before deciding whether to retry.
</Warning>

## Error fields

<ResponseField name="message" type="string" required>
  Human-readable failure reason. The set of messages is not a stable machine-readable enum.
</ResponseField>

<ResponseField name="status" type="integer" required>
  Always `500` for errors emitted by the current public API helper.
</ResponseField>

## Retry guidance

* Fix the request before retrying validation messages such as `No file id provided` or `Invalid folder`.
* Ask the account owner to regenerate or verify the key after `Invalid API Key`.
* Retry `Too many requests!` only after the thumbnail limit window has passed. Thumbnail updates allow at most three attempts per minute.
* Poll remote-upload status instead of repeatedly submitting the same URL. Duplicate queued URLs return `URL already in queue`.
* Use bounded retries with backoff only for transport failures and temporary upstream errors.

## Example handler

```javascript theme={null}
async function videobaseRequest(path, options = {}) {
  const response = await fetch(`https://api.videobase.com/v1${path}`, {
    ...options,
    headers: {
      Accept: "application/json",
      "X-Api-Key": process.env.VIDEOBASE_API_KEY,
      ...options.headers,
    },
  });

  const data = await response.json();

  if (!response.ok) {
    throw new Error(data.message ?? `Videobase request failed (${response.status})`);
  }

  return data;
}
```