Vamo API errors: what each status and code means

Article summary

Every Vamo API error body carries a code, a message and a status, plus detail fields that depend on the error.
A 401 from the Vamo API means the key is missing, wrong or revoked, or the key is set to require signed requests.
A 403 from the Vamo API means the key or role lacks a permission, or a feature is off.
Every Vamo API response has an x-request-id header, and the request ID is not in the response body.
A Vamo API key can never reach projects, outreach, members, billing or key management.

Every Vamo API error has the same shape: a code, a message and a status. Some errors add detail fields that say exactly what went wrong. The table below lists each error, what it means and what to do.

The errors

Status	Code	What it means	What to do
400	`bad_request`	The request is malformed.	Read `validation.issues`. Each issue names a `path` and a `message`. Fix those fields and send again.
401	`unauthorized`	No key was sent, or the key is wrong or revoked.	Check the key at Set up > API keys. Call `GET /v1/me` to test it.
401	`signature_required`	This key is set to require signed requests.	Sign the request, or use a key without that setting.
402	`payment_required`	The plan does not include this, the account is out of balance, or a quota is reached.	Read `entitlement` and `plan`, or `reason`, or `quota`. The account owner resolves it in the Vamo app.
403	`forbidden`	The key or role lacks a permission, or a feature is off.	Read `entitlement` for the missing permission, or `reason`. Change the key's permissions or use another key.
404	`not_found`	No such route or record.	Check the path against the reference. Check the ID you sent.
409	`conflict`	The request conflicts with the current state.	Read `message`. It says what is in the way.
422	`unprocessable_entity`	The request is well formed but cannot be processed.	Read `message` and change the request.
429	`too_many_requests`	A rate limit, a quota or a cap set by the account owner was reached.	Read `retryAfterSeconds`, `quota` or `reason`. Wait, then send again.
5xx	`internal_error`	Vamo failed.	Keep the request ID. If it keeps happening, send it to us.

The API reference has the full shape of every request and response.

Reading the detail fields

Start with code. It is stable, so your program can branch on it. The message is written for a person.

Detail fields sit beside code at the top level of the body. Here is a 400 for a request that left out a required field:

{
  "code": "bad_request",
  "message": "Validation failed",
  "status": 400,
  "validation": {
    "issues": [{ "path": "query", "code": "invalid_type", "message": "Required" }]
  }
}

The path uses dots for nested fields. A real body can carry more fields than this example.

A few notes on the other fields:

entitlement names one permission. On a 403 the key or role does not hold it. On a 402 the plan does not include it.
quota appears when a quota is reached. A key can read its own quotas at GET /v1/quotas.
retryAfterSeconds appears on a 429 when a wait is known. The response then also has a Retry-After header.

A 403 is also the answer when a key calls a route meant only for the Vamo app. A key can never reach projects, outreach, members, billing or key management. See using the Vamo API for what a key can do.

For a 402, the account owner can see where the account stands on the Usage page. For a 429 that keeps coming back, read too many requests.

The request ID

Every response has an x-request-id header. It is on successes and errors alike. The request ID is not in the body, so read it from the headers.

Log it with every error. If you send your own x-request-id header, Vamo returns the same value. When you report a problem, send the request ID with the status and code. Never send the key itself. See keep your API key safe.

An AI tool connected through MCP cannot see the request ID. A plan or billing refusal reaches it as one fixed sentence, with no code. If your assistant reports one, read this Vamo account cannot run that right now.

Still stuck

Let your coding agent check its own connection. It reports what works and what to pass on to Vamo.

Hand this to your agent

Paste this line into your assistant. It reads Vamo's troubleshooting guide, runs the checks, and tells you what it found.

Read https://vamotalent.ai/skills/vamo-troubleshooting.md and check your connection to Vamo. Tell me in plain words what is wrong and what I should do.

FAQs

What does 401 unauthorized mean on the Vamo API?

The Vamo API did not accept the key. No key was sent, or the key is wrong or revoked. Check the key at Set up > API keys in the Vamo app. A lost key cannot be shown again, so create a new one and revoke the old one.

What does 403 forbidden mean on the Vamo API?

The Vamo API recognized the key, but the key or the role of its owner lacks a permission, or a feature is off. The entitlement field in the error body names the missing permission. An API key that calls a route meant only for the Vamo app also gets 403.

Where is the request ID on a Vamo API error?

The request ID is in the x-request-id header of every Vamo API response. It is not in the response body. An AI tool connected to Vamo through MCP cannot see it.

Still stuck? Tell us.