> ## 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>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.