Skip to main content
The Padel API uses conventional HTTP response codes to indicate the success or failure of an API request.
Code RangeDescription
2xxSuccess — The request was successful
3xxRedirection — The resource has moved
4xxClient Error — Something is wrong with the request
5xxServer Error — Something went wrong on our end

​
Success Codes

​
200 - OK

The request was successful and the response contains the requested data. 
{
  "data": [...],
  "meta": {
    "current_page": 1,
    "total": 42
  }
}

​
Redirection Codes

​
302 - Found (Redirect)

The requested resource has been moved to a new location. This typically happens when a player or tournament record has been updated or merged with new data. How to handle:
  • Follow the redirect URL provided in the Location header
  • Update any cached references to use the new URL
  • Most HTTP clients handle redirects automatically
# Example: Player data was merged
curl -i 'https://padelapi.org/api/players/123'

HTTP/1.1 302 Found
Location: https://padelapi.org/api/players/456

​
Client Error Codes

​
401 - Unauthenticated

Authentication failed. Your API token is missing, invalid, or has been revoked. How to fix:
  1. Verify you’re including the Authorization header in your request
  2. Check that your token format is correct: Bearer YOUR_API_TOKEN
  3. Generate a new token at API Tokens if needed
# Correct format
curl -X GET 'https://padelapi.org/api/seasons' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'

{
  "message": "Unauthenticated."
}
Never share your API token publicly or commit it to version control.

​
402 - Payment Required

Your current subscription plan does not include access to this resource or you have exceeded your plan limits. How to fix:
  1. Check your current plan at padelapi.org/billing
  2. Upgrade your subscription to access premium endpoints
  3. Review the pricing plans for available features
{
  "message": "Subscription required.",
  "contact_email": "[email protected]",
  "error_time": "2026-01-19 15:42:31"
}

​
404 - Not Found

The requested resource does not exist. This can happen when:
  • The ID doesn’t exist in the database
  • The resource was deleted
  • There’s a typo in the endpoint URL
How to fix:
  1. Verify the resource ID is correct
  2. Check the endpoint URL for typos
  3. Use a list endpoint to find valid IDs
{
  "message": "Not found.",
  "contact_email": "[email protected]",
  "error_time": "2026-01-19 15:42:31"
}

​
422 - Unprocessable Entity

The request parameters failed validation. The response includes details about which parameters are invalid. How to fix:
  1. Review the error message for specific validation failures
  2. Check parameter types (string vs integer)
  3. Verify required parameters are included
  4. Ensure values are within allowed ranges
{
  "message": "The selected category is invalid.",
  "errors": {
    "category": [
      "The selected category is invalid."
    ]
  }
}

​
429 - Too Many Requests

You have exceeded the API rate limit. 
{
  "message": "Too Many Attempts."
}
How to handle:
  1. Wait until the next minute before retrying
  2. Monitor the X-RateLimit-Remaining header to avoid hitting the limit
  3. Implement request throttling in your application
See Rate Limits for details on limits and available headers.

​
Server Error Codes

​
500 - Internal Server Error

Something went wrong on our servers. We automatically log all errors and work to fix them as quickly as possible. How to handle:
  1. Wait a few moments and retry your request
  2. If the error persists, contact us with the error_time included in the response
{
  "message": "Server Error",
  "contact_email": "[email protected]",
  "error_time": "2026-01-19 15:42:31"
}
When reporting a 500 error, please include the error_time from the response. This helps us locate and fix the issue faster.
Contact support: [email protected]

​
Best Practices

  1. Always check the status code before processing the response body
  2. Handle redirects — Configure your HTTP client to follow 302 redirects
  3. Implement retry logic for 500 errors with exponential backoff
  4. Log error responses to help debug integration issues
  5. Include error_time when reporting server errors to support