> ## Documentation Index > Fetch the complete documentation index at: https://docs.squadassist.ai/llms.txt > Use this file to discover all available pages before exploring further. # Error Codes — HTTP Status Reference > All HTTP error codes returned by the SquadAssist API, their JSON response bodies, common causes, and troubleshooting guidance for each status code. The SquadAssist API uses standard HTTP status codes to signal the outcome of every request. Successful requests return `2xx` codes. Client errors return `4xx` codes with a JSON body that explains what went wrong. Server errors return `5xx`. Every error response contains at minimum an `"error"` key with a human-readable string. ## Error response format ```json theme={null} { "error": "" } ``` Some responses include additional fields. The 429 rate-limit response includes `limit`, `window_seconds`, and `retry_after_seconds`. The 400 response for an invalid role includes the list of allowed values in `allowed_roles`. ## Error codes | Status | Name | Description | | ------ | --------------------- | ------------------------------------------------- | | `400` | Bad Request | Missing required field or invalid parameter value | | `401` | Unauthorized | Missing or invalid authentication credentials | | `403` | Forbidden | Credentials are valid but access is denied | | `404` | Not Found | The requested player or club does not exist | | `429` | Too Many Requests | Rate limit exceeded; see `retry_after_seconds` | | `500` | Internal Server Error | Unexpected server-side error | *** ## 400 Bad Request The request was well-formed but contained a missing or invalid parameter. Common `"error"` values: * `"player_id is required"` — you omitted the `player_id` field * `"club_id is required"` — you omitted the `club_id` field * `"Invalid player_id"` — the `player_id` value failed format validation * `"Invalid target_club_id"` — the `target_club_id` value failed format validation * `"Invalid contract_end_date, must be in the format YYYY-MM-DD"` — date string is malformed * `"currency_code must be a string"` — wrong type passed for `currency_code` * `"Invalid role"` — the `role` query parameter is not a recognised SquadAssist role; the response also includes `"allowed_roles"` listing valid values * `"At least one of transfermarkt_id or wyscout_id or squadassist_id must be provided"` — `POST /query_player` requires at least one ID field * `"Body must be a JSON object"` — request body is not a JSON object **Troubleshooting:** Check your request body and query parameters against the endpoint reference. Ensure all required fields are present and that IDs and currency codes use the expected format (ISO 4217 for currency, `YYYY-MM-DD` for dates). *** ## 401 Unauthorized Your request did not include valid credentials, or the credentials have been revoked. Common `"error"` values: * `"Missing API key"` — no API key was found in `x-api-key` or `Authorization` headers * `"Invalid API key"` — the key was found but does not match any active key in the system, or the key length is outside the valid range * `"API key is revoked"` — the key was valid but has been revoked * `"Invalid email or password"` — credentials supplied to `POST /auth/login` are incorrect **Troubleshooting:** Confirm you are sending the API key in the correct header (`x-api-key: ` or `Authorization: Bearer `). If your key was recently generated, verify you are using the raw key value and not an ID or hash. If you receive `"API key is revoked"`, contact SquadAssist to issue a replacement key. *** ## 403 Forbidden Your credentials are valid but you are not permitted to perform this action. Common `"error"` values: * `"Account access denied: "` — your account is inactive, still in the registered (unactivated) state, or your plan does not grant access * `"Player is not in the allowed leagues"` — the player you requested is outside the leagues covered by your plan * `"Requested club is not allowed"` — the `club_id` you provided is not in the set of clubs in your coverage **Player analysis not yet available:** Some players exist in the SquadAssist database but do not yet have analysis data prepared. If you request analysis for such a player (via `/get_roi_analysis`, `/get_future_transfer_value`, or `/get_sportive_impact`), the API returns `403` with a message indicating the player's analysis is not ready. The player's data is present but `analysis_available` is `false` for that record. To check availability before running analysis, call `GET /player_info` first. **Troubleshooting:** If you receive an account access denied error, check your account status and plan with SquadAssist. *** ## 404 Not Found The resource you requested does not exist in the SquadAssist database. Common `"error"` values: * `"Player not found"` — no player matches the provided `player_id`, `transfermarkt_id`, or `wyscout_id` * `"Club not found"` — no club matches the provided `club_id` or `transfermarkt_id` **Troubleshooting:** Use `POST /query_player` or `POST /query_club` to resolve IDs from Transfermarkt or Wyscout to SquadAssist IDs before calling analysis endpoints. A `404` is distinct from a `403` for player visibility — a `404` means the player is genuinely not in the database. *** ## 429 Too Many Requests You have exceeded the rate limit of 60 requests per minute for your API key. ```json theme={null} { "error": "Rate limit exceeded", "limit": 60, "window_seconds": 60, "retry_after_seconds": 14 } ``` **Troubleshooting:** Wait for the number of seconds in `retry_after_seconds` before retrying. Do not retry immediately — the window is rolling and a premature retry will return another 429. See [Rate limits](/api-reference/rate-limits) for strategies to avoid hitting this limit. *** ## 500 Internal Server Error An unexpected error occurred on the server. ```json theme={null} { "error": "Unexpected server error. Please try again later." } ``` **Troubleshooting:** This is not caused by your request parameters. Retry the request after a short delay. If the error persists, contact SquadAssist support with the endpoint, request body, and approximate timestamp.