Response Codes

​

Success Codes

​

200 - OK

{
  "data": [...],
  "meta": {
    "current_page": 1,
    "total": 42
  }
}

​

Redirection Codes

​

302 - Found (Redirect)

• 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

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."
}

​

402 - Payment Required

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 ID doesn’t exist in the database
• The resource was deleted
• There’s a typo in the endpoint URL

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

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

{
  "message": "Too Many Attempts."
}

1. Stop sending requests until Retry-After has passed, then resume
2. Do not retry in a loop: every request made while limited is rejected too, and keeps your client blocked
3. Monitor the X-RateLimit-Remaining header to avoid hitting the limit
4. Implement request throttling in your application. The Logs & Quota page shows your daily and monthly consumption

​

Server Error Codes

​

500 - Internal Server Error

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"
}

​

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