Skip to main content
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

{
  "error": "<description>"
}
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

StatusNameDescription
400Bad RequestMissing required field or invalid parameter value
401UnauthorizedMissing or invalid authentication credentials
403ForbiddenCredentials are valid but access is denied
404Not FoundThe requested player or club does not exist
429Too Many RequestsRate limit exceeded; see retry_after_seconds
500Internal Server ErrorUnexpected 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: <key> or Authorization: Bearer <key>). 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: <reason>" — 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. 
{
  "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 for strategies to avoid hitting this limit.

​
500 Internal Server Error

An unexpected error occurred on the server. 
{
  "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.