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

# Errors

> Common Public API error responses and how to debug them.

Error responses use a JSON body with an `error` code string you can branch on in clients.

```json theme={null}
{
  "error": "forbidden"
}
```

## Authentication and authorization

| Status | `error`               | What to check                                                              |
| ------ | --------------------- | -------------------------------------------------------------------------- |
| 401    | `unauthorized`        | Header present? Using `x-api-key`?                                         |
| 401    | `invalidApiKey`       | Key copied correctly? Not revoked or expired?                              |
| 403    | `forbidden`           | Key permissions and organization match the request?                        |
| 403    | `featureNotAvailable` | Plan includes this feature (for example Rocket League tags or API access)? |
| 429    | `rateLimited`         | Too many requests with this key — wait and retry                           |

## Validation and not found

| Status | Common `error` values                                                                                                                                                                                                                                 |
| ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400    | `invalidRequest`, `invalidStatus`, `alreadyConverted`, `playerCreateFailed`, `convertFailed`, `invalidPlayer`, `invalidTeam`, `invalidTeamRole`, `invalidFileType`, `fileTooLarge`, `unsupportedContentType`, `duplicateGame`, `invalidDiscordUserId` |
| 404    | `teamNotFound`, `playerNotFound`, `documentNotFound`, `notFound`                                                                                                                                                                                      |
| 409    | `discordUserIdTaken`, `alreadyApplied`                                                                                                                                                                                                                |
| 413    | `payloadTooLarge`                                                                                                                                                                                                                                     |
| 500    | `internalServerError`, `uploadUrlFailed`, `downloadUrlFailed`                                                                                                                                                                                         |

Exact codes depend on the endpoint. See the API reference for operation-specific responses.

## Debugging tips

1. Confirm the base URL is `https://api.squadvault.xyz/v1`.
2. Confirm the organization ID in the path, query, or body matches the key’s organization. Tryout get/update/convert always require `organizationId` (`?organizationId=` on GET, JSON body on PATCH/POST).
3. Confirm the key has the permission listed in [Permissions](/api/permissions).
4. For uploads, confirm `contentType` is allowed and `fileKey` starts with `documents/{organizationId}/`.