Error codes
What ApiVault returns when a request fails, what each code means, and how to fix it.
Error format
The REST API returns a JSON body with a readable error message. Errors a program might want to handle also carry a stable code. Check the code rather than the message, which can change.
{
"error": "That vault key is incorrect.",
"code": "INVALID_VAULT_KEY"
}The CLI prints the message, or the same object with --json, and exits with code 1.
HTTP status codes
| Status | Meaning |
|---|---|
400 | The request is missing something or is malformed |
401 | No valid credential, or a vault key is needed |
403 | The credential is valid but not allowed to do this |
404 | Not found, or outside what this credential can see |
409 | Conflicts with something that already exists |
429 | Too many attempts; the Retry-After header says how many seconds to wait |
500 | Something failed on our side; try again, then check the system status |
Error codes
| Code | Status | Meaning | Fix |
|---|---|---|---|
VAULT_KEY_REQUIRED | 401 | The project uses custom encryption and no vault key was sent | Send the vault key, or use --vault-key or APIVAULT_KEY in the CLI |
INVALID_VAULT_KEY | 403 | The vault key is wrong | Send the right one. Repeated failures lead to VAULT_KEY_RATE_LIMITED |
VAULT_KEY_RATE_LIMITED | 429 | Too many wrong vault keys | Wait for the Retry-After delay. See attempt limits |
DUPLICATE_KEY | 409 | A key with that name already exists in that environment; conflicts lists them | Update the existing key, or use another name or environment |
INSUFFICIENT_SCOPE | 403 | The token lacks the scope this needs | Create a token with that scope |
PROJECT_MISMATCH | 403 | The request names a project other than the service token's own | Remove the project, or use that project's token |
ENVIRONMENT_MISMATCH | 403 | The request names an environment other than the token's pin | Remove the environment, or use a token for that one |
Service token refusals
These responses carry only a message, with no code. The project's audit log records each one under the event type shown.
| Status | Message | Audit event | Fix |
|---|---|---|---|
401 | This service token expired. | SERVICE_TOKEN_EXPIRED | Create a new token |
401 | This service token has been revoked. | SERVICE_TOKEN_REVOKED | Create a new token |
403 | This service token is not allowed from this IP address. | SERVICE_TOKEN_DENIED_IP | Update the IP allowlist |
A plain 401 Unauthorized means the value never matched a token at all, usually because of a truncated copy or a secret set on the wrong repository.
MCP tool errors
MCP tools use the same codes, plus UNAUTHORIZED, NOT_FOUND, VALIDATION and DECRYPT_FAILED. What an agent should do about each one is on MCP tools & scopes.