# Troubleshooting

When your agent's call to VidLab fails, the answer says why: every error has a `code` (see [Errors](/vidlab-api/docs/errors)). These are the ones agents meet most.

| What you see | Why | Fix |
| - | - | - |
| `401` `unauthorized` | The key is missing, mistyped or revoked, or the agent did not send it. | Check the key is set (below), then that the call sends `Authorization: Bearer $VIDLAB_API_KEY`. Make a new key on [API keys](https://vidlab.ai/vidlab-api/api-keys) if it was revoked. |
| `404` `not_found` | Wrong base URL or path. | The base URL is `https://vidlab.ai/v1`, and paths are the ones in the [Quickstart](/vidlab-api/docs/quickstart). |
| `404` `model_not_found` | The model id is not in the list (an invented or old name). | Ask the agent to list models (`GET /v1/models?search=...`) and use an id from there. |
| `400` `invalid_input` | A field or value the model does not take. The message names it and the allowed values. | Ask the agent to read the model (`GET /v1/models/{id}`) and send only its `params`. |
| `429` `api_wallet_exhausted` | The balance cannot cover the price. | Add credit on [Billing](https://vidlab.ai/vidlab-api/billing). The agent should not retry until then. |
| `429` `rate_limited` | More than 20 jobs started in 10 seconds on this account (not queued). | Wait the `Retry-After` seconds, then send it again; polling never counts. |
| `422` `max_cost_exceeded` | The job costs more than the cap the agent sent. | Raise the cap only if you agree to the price in `price_usd`. |

## The key is not picked up

The agent reads `VIDLAB_API_KEY` from the environment it was started in. If it says the key is missing:

1. Check it is set, without printing it:

```bash macOS / Linux
test -n "$VIDLAB_API_KEY" && echo set || echo missing
```

```powershell Windows PowerShell
if ($env:VIDLAB_API_KEY) { "set" } else { "missing" }
```

2. If it says `missing`, set it again ([how](/vidlab-api/docs/agent-skill#1-set-your-key)) and **open a new terminal**: a terminal that was already open does not see the change.
3. Start the agent from that terminal. An app started from the Dock or the Start menu may not see a variable set in your shell profile.

## The skill does not install

- `npx skills add https://vidlab.ai` needs Node.js 18 or newer (`node --version`) and the exact address `https://vidlab.ai`.
- "No skills found at this URL": check the address, then that https://vidlab.ai/.well-known/agent-skills/index.json opens in your browser.
- Install by hand instead: [Install the VidLab skill](/vidlab-api/docs/agent-skill#or-by-hand).

## The agent does not use the skill

Name it in your request ("use the VidLab skill") and check where it was installed: `~/.claude/skills/vidlab` for Claude Code, `~/.agents/skills/vidlab` for Codex and Cursor (or the project's own skills folder without `-g`).

## Still stuck

Every answer carries an `X-Request-Id` header. Send it with what you asked to support@vidlab.ai.