Skip to main content

​
Error Format

All errors return JSON: 
{
  "error": "Error message",
  "detail": "More details"
}
Or for validation errors: 
{
  "field_name": ["Error message"],
  "email": ["This field is required."]
}

​
Common Errors

​
400 Bad Request

Missing required fields: 
{
  "password": ["This field is required."]
}
Solution: Check your request and include all required fields. Duplicate username: 
{
  "username": ["This username is already taken in your organization."]
}
Solution: Use a different username or let it auto-generate.

​
401 Unauthorized

Missing token: 
{
  "detail": "Authentication credentials were not provided."
}
Solution: Include Authorization: Bearer YOUR_TOKEN header. Expired token: 
{
  "detail": "Token is expired"
}
Solution: Use your refresh token to get a new access token.

​
403 Forbidden

Insufficient permissions: 
{
  "detail": "You do not have permission to perform this action."
}
Solution: Only admin users can create, update, or delete. Use an admin account.

​
404 Not Found

Resource not found: 
{
  "detail": "Not found."
}
Solution: Check the ID exists and belongs to your organization.

​
Example Error Handling

import requests

def create_student(token, data):
    headers = {"Authorization": f"Bearer {token}"}

    try:
        response = requests.post(
            "https://api.chessplay.io/api/v1/students/",
            headers=headers,
            json=data
        )
        response.raise_for_status()
        return response.json()

    except requests.exceptions.HTTPError as e:
        if e.response.status_code == 400:
            print(f"Validation error: {e.response.json()}")
        elif e.response.status_code == 401:
            print("Authentication failed. Login again.")
        elif e.response.status_code == 403:
            print("Need admin permissions.")
        else:
            print(f"Error: {e.response.status_code}")
        return None

​
HTTP Status Codes

CodeMeaning
200Success
201Created
204Deleted
400Bad request
401Unauthorized
403Forbidden
404Not found
500Server error