> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ozura.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Common Errors

> Frequent Vault API errors and how to resolve them.

Solutions for frequently encountered Vault API errors.

## Authentication

| Message                     | Causes                                    | Solutions                                      |
| --------------------------- | ----------------------------------------- | ---------------------------------------------- |
| `Invalid API key`           | Wrong key, deleted key, wrong environment | Verify key, check dashboard, use correct env   |
| `Token expired`             | JWT expired                               | Re-authenticate via `/auth/login`, get new JWT |
| `MFA verification required` | MFA not verified                          | Call `/auth/mfa/verify` or use backup code     |

## Tokens and CVC

| Message                            | Causes                                | Solutions                                                     |
| ---------------------------------- | ------------------------------------- | ------------------------------------------------------------- |
| `Token not found`                  | Invalid token, wrong project, deleted | Check token ID, project, and that token exists                |
| `CVC session expired or not found` | >90 sec, already used, invalid ID     | Re-tokenize with CVV for new session                          |
| `Invalid card number`              | Luhn fail, wrong length, non-numeric  | Card must be 13–19 digits; validate Luhn, strip spaces/dashes |
| `Card has expired`                 | Past expiration                       | Use current or future expiry                                  |

## Permissions

| Message                                                    | Causes               | Solutions                              |
| ---------------------------------------------------------- | -------------------- | -------------------------------------- |
| `This API key does not have permission for this operation` | Key lacks permission | Check app permissions in dashboard     |
| `Only admins and owners can...`                            | Insufficient role    | Use admin/owner user or request access |

## Rate limits

| Message                    | Solution                                             |
| -------------------------- | ---------------------------------------------------- |
| `Rate limit exceeded`      | Wait `retry_after_seconds`; use exponential backoff  |
| `Too many failed attempts` | Wait for lockout; verify credentials before retrying |

## Proxy

| Message                   | Causes                     | Solutions                            |
| ------------------------- | -------------------------- | ------------------------------------ |
| `Failed to proxy request` | Bad URL, PSP down, network | Check `proxy_url`, PSP status, retry |
| `Invalid proxy URL`       | Malformed or non-HTTPS     | Use full `https://` URL              |

## Validation

| Message                     | Solutions                                                                                   |
| --------------------------- | ------------------------------------------------------------------------------------------- |
| `Missing required field: X` | Include all required fields; check JSON shape                                               |
| `Invalid value for X`       | Check type (string vs number) and format per [API Reference](/api-reference/vault/overview) |

## Getting help

If the error persists: check [Guides](/guides/vault/overview), review [audit logs](/guides/vault/audit-logs/overview), and contact support with error message, redacted request, timestamp, and project ID.