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

# API Error Codes and Troubleshooting

> Every Veedcrawl error follows a consistent JSON shape. Learn the HTTP status codes, job-level error fields, and how to fix common problems.

All Veedcrawl API errors follow a consistent JSON shape so you can handle them predictably in your code. The `error` field is a machine-readable code, and `message` gives a plain-language description of what went wrong.

## Error response format

```json theme={null}
{
  "error": "error-code",
  "message": "Human-readable description",
  "details": null,
  "documentationUrl": null
}
```

## HTTP status codes

| Status | Meaning               | Common cause                                            |
| ------ | --------------------- | ------------------------------------------------------- |
| 200    | OK                    | Request succeeded                                       |
| 400    | Bad Request           | Missing required parameter or invalid URL               |
| 401    | Unauthorized          | Missing or invalid `x-api-key` header                   |
| 403    | Forbidden             | Insufficient credits or plan restriction                |
| 429    | Too Many Requests     | Rate limit exceeded                                     |
| 500    | Internal Server Error | Job failed on the server side                           |
| 504    | Gateway Timeout       | Transcript or extraction job timed out (\~3 min window) |

## Job-level errors

Transcript and extraction jobs are asynchronous. When you poll a job and its `status` is `"failed"`, the response includes an `error` object with `code` and `message` fields describing what went wrong with that specific job.

## Troubleshooting

<AccordionGroup>
  <Accordion title="I'm getting 401 errors">
    Check that you are passing your API key in the `x-api-key` header — not the `Authorization` header. Confirm the key is valid and has not been revoked by visiting your dashboard or calling `GET /v1/keys`.
  </Accordion>

  <Accordion title="My transcript job failed">
    Verify that the video URL is public and that the platform is supported. Private, unlisted, or age-restricted videos may not be accessible. If you are using `mode=generate` (Whisper), try switching to `mode=native` first to rule out a URL problem.
  </Accordion>

  <Accordion title="I'm getting 429 Too Many Requests">
    You have hit the rate limit for that endpoint tier. Read the `X-RateLimit-Reset` header in the response — it contains a Unix timestamp indicating when your window resets. Wait until that time before retrying.
  </Accordion>

  <Accordion title="My extract job timed out">
    Extraction watches the full video, so very long videos can exceed the \~3 minute processing window and return a 504. Try submitting the request again, or use a shorter clip if possible.
  </Accordion>
</AccordionGroup>