Skip to main content
The Poelis Public API uses standard HTTP status codes and returns structured error responses to help you handle errors gracefully.

​
Error Response Format

All error responses follow this structure: 
{
  "error": "error_code",
  "message": "Error message with details",
}

​
Common Error Codes

​
400 Bad Request

Invalid request parameters or malformed request body. 
{
  "error": "validation_error",
  "message": "Invalid request parameters",
}

​
401 Unauthorized

Missing or invalid API key. 
{
  "error": "unauthorized",
  "message": "Invalid or missing API key"
}

​
403 Forbidden

Valid API key but insufficient permissions to access the resource. 
{
  "error": "forbidden",
  "message": "Access denied to this resource"
}

​
404 Not Found

Resource not found or not accessible. 
{
  "error": "not_found",
  "message": "Workspace not found or not accessible"
}

​
422 Unprocessable Entity

Validation error (e.g., invalid data format). 
{
  "error": "validation_error",
  "message": "Invalid data format",
}

​
429 Too Many Requests

Rate limit exceeded. See Rate Limiting. Response includes Retry-After and X-RateLimit-* headers. 
{
  "error": "rate_limit_exceeded",
  "message": "Too many requests"
}

​
500 Internal Server Error

Server-side error. If this persists, contact support. 
{
  "error": "internal_error",
  "message": "An internal error occurred"
}

​
Request ID

All responses include an X-Request-ID header for tracking and debugging: 
X-Request-ID: 550e8400-e29b-41d4-a716-446655440000
Include this ID when contacting support about errors.

​
Error Handling Best Practices

Check Status Codes

Always check HTTP status codes before processing responses

Log Request IDs

Log X-Request-ID for debugging and support requests

​
Getting Help

If you encounter persistent errors:
  1. Check the X-Request-ID header in the error response
  2. Review the error message and details
  3. Contact [email protected] ↗︎ with:
    • The X-Request-ID
    • The error code and message
    • Steps to reproduce