Skip to main content
The API uses standard HTTP status codes and returns errors in a consistent JSON format.

​
Error response format

All error responses include a detail field: 
{
  "detail": "Contact not found"
}
For validation errors, the response includes structured field-level details: 
{
  "detail": [
    {
      "loc": ["body", "email"],
      "msg": "value is not a valid email address",
      "type": "value_error.email"
    }
  ]
}

​
Status codes

CodeMeaningDescription
200OKRequest succeeded
201CreatedResource successfully created
204No ContentRequest succeeded with no response body (deletes)
400Bad RequestInvalid request body or parameters
401UnauthorizedMissing or invalid authentication
403ForbiddenValid auth but insufficient permissions
404Not FoundResource does not exist
409ConflictResource already exists or conflicts with current state
422Unprocessable EntityRequest body failed validation
429Too Many RequestsRate limit exceeded
500Internal Server ErrorUnexpected server error

​
Handling errors

import requests

response = requests.get(
    "https://api.socrateslabs.io/api/contacts/invalid-id",
    headers={"X-API-Key": "sk_your_api_key_here"},
)

if response.status_code == 404:
    print("Contact not found")
elif response.status_code == 401:
    print("Check your API key")
elif response.status_code >= 400:
    error = response.json()
    print(f"Error: {error['detail']}")