> For the complete documentation index, see [llms.txt](https://vampauth.gitbook.io/vampauth-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://vampauth.gitbook.io/vampauth-docs/troubleshooting/api-errors.md).

# Management API errors

V2 errors use this shape:

```json
{
  "error": { "code": "VALIDATION_ERROR", "message": "Some fields are invalid.",
    "details": [{ "field": "name", "code": "example", "message": "Check this field." }] },
  "meta": { "request_id": "req_example" }
}
```

Details are optional. Keep the request ID when asking for help; it also appears in X-Request-Id. Code names vary by operation, so handle the HTTP status as well.

## Authentication and access

| HTTP | Code                                                    | Meaning / fix                                                            |
| ---- | ------------------------------------------------------- | ------------------------------------------------------------------------ |
| 401  | UNAUTHORIZED                                            | Missing, expired, revoked, or invalid bearer; replace/check the token    |
| 401  | SESSION\_REQUIRED                                       | Token administration needs browser sign-in                               |
| 403  | INSUFFICIENT\_SCOPE                                     | Add the operation's scope to a replacement token                         |
| 403  | FORBIDDEN                                               | Current account/team capability or project grant is missing              |
| 403  | PLAN\_REQUIRED                                          | Settings exceed the owner's effective allowance                          |
| 403  | INVALID\_ORIGIN                                         | Use the trusted signed-in dashboard for token mutations                  |
| 404  | NOT\_FOUND / RESOURCE\_NOT\_FOUND / PROJECT\_NOT\_FOUND | Resource missing or inaccessible; check UUID, project and current access |
| 404  | TOKEN\_NOT\_FOUND / ACCOUNT\_NOT\_FOUND                 | Token/account administration target isn't available                      |

A read token cannot become a write token by changing the request method. A write scope also doesn't imply its read counterpart.

## Request validation

| HTTP | Code                       | Fix                                                            |
| ---- | -------------------------- | -------------------------------------------------------------- |
| 400  | INVALID\_JSON              | Send valid JSON where required                                 |
| 400  | INVALID\_BODY              | Check request streaming/body construction                      |
| 400  | INVALID\_UTF8              | Encode source and fields as valid UTF-8                        |
| 400  | INVALID\_MULTIPART         | Let your client generate a valid multipart boundary            |
| 400  | INVALID\_QUERY             | Remove unknown/duplicate filters and fix ranges/types          |
| 400  | INVALID\_CURSOR            | Restart traversal with matching filters/grants                 |
| 400  | INVALID\_IF\_MATCH         | Send one strong tag for the correct resource                   |
| 400  | IDEMPOTENCY\_KEY\_REQUIRED | Supply a stable key for this operation                         |
| 400  | INVALID\_IDEMPOTENCY\_KEY  | Use 1–128 visible ASCII characters, or a UUID where required   |
| 405  | METHOD\_NOT\_ALLOWED       | Use a supported method; inspect Allow                          |
| 413  | PAYLOAD\_TOO\_LARGE        | Reduce actual source/body/overhead bytes                       |
| 415  | UNSUPPORTED\_MEDIA\_TYPE   | Use the endpoint's JSON, multipart, or text/plain type         |
| 422  | VALIDATION\_ERROR          | Inspect details, cross-field rules and same-project references |

## State and concurrency

| HTTP | Code                                                      | Fix                                                                                                           |
| ---- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| 409  | DUPLICATE\_KEY / DUPLICATE\_PROJECT / DUPLICATE\_RESOURCE | Choose another key/name/alias or reuse the intended existing resource                                         |
| 409  | QUOTA\_EXCEEDED / TOKEN\_LIMIT\_REACHED                   | Inspect the relevant current resource allowance; remove unused resources or choose an allowed action          |
| 409  | KEY\_STATE\_CONFLICT                                      | The key can't perform this lifecycle action: for example reset an unbound key or renew lifetime/banned access |
| 409  | IDEMPOTENCY\_CONFLICT                                     | Reuse only the original target/body/precondition; new intent needs a separate request                         |
| 409  | CONFIGURATION\_CHANGED                                    | Publishing configuration changed; re-read and plan a new independent operation                                |
| 409  | LOADSTRING\_DISABLED                                      | Destination project has loader delivery disabled                                                              |
| 409  | OUTPUT\_UNAVAILABLE                                       | A protected payload required for the action isn't available                                                   |
| 412  | PRECONDITION\_FAILED / REVISION\_MISMATCH                 | Resource changed since your read; reconcile before a new write                                                |
| 428  | PRECONDITION\_REQUIRED                                    | Read the resource and send its ETag as If-Match                                                               |

For an uncertain idempotent write, replay its original context. Don't fix a replay conflict by silently changing ETag/body under the same key.

## Temporary failures

429 RATE\_LIMITED: honor Retry-After and the rate headers. 503 SERVICE\_UNAVAILABLE: a dependency, publisher, authentication store or limiter couldn't complete the request. Back off and preserve idempotency context. An internal 500 also indicates server failure; retain the request ID. Don't retry permanent validation/permission failures in a loop.

Standalone key-check errors use lowercase codes and a simpler body. See its endpoint page rather than assuming the v2 envelope.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://vampauth.gitbook.io/vampauth-docs/troubleshooting/api-errors.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.