Skip to main content

Documentation Index

Fetch the complete documentation index at: https://padelapi.org/docs/llms.txt

Use this file to discover all available pages before exploring further.

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": "ferran@padelapi.org",
  "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": "ferran@padelapi.org",
  "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": "ferran@padelapi.org",
  "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: ferran@padelapi.org

​
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