Errors, Rate Limits & Pagination
Error Handling
All errors follow a consistent format:
1{2 "error": {3 "code": "VALIDATION_ERROR",4 "message": "Invalid workflow ID format",5 "details": {6 "field": "workflow_id",7 "constraint": "must be alphanumeric with hyphens"8 },9 "request_id": "req_xyz789"10 }11}HTTP Status Codes
| Code | Meaning |
|---|---|
| 200 | Success |
| 201 | Created |
| 204 | No Content |
| 400 | Bad Request - Invalid input |
| 401 | Unauthorized - Missing or invalid token |
| 403 | Forbidden - Insufficient permissions |
| 404 | Not Found - Resource doesn't exist |
| 409 | Conflict - Resource already exists |
| 422 | Unprocessable Entity - Validation failed |
| 429 | Too Many Requests - Rate limit exceeded |
| 500 | Internal Server Error |
| 503 | Service Unavailable |
Error Codes
| Code | Description |
|---|---|
AUTHENTICATION_REQUIRED | Missing authentication |
INVALID_TOKEN | Token is invalid or expired |
PERMISSION_DENIED | Insufficient permissions |
VALIDATION_ERROR | Request validation failed |
RESOURCE_NOT_FOUND | Requested resource not found |
RESOURCE_CONFLICT | Resource already exists |
RATE_LIMIT_EXCEEDED | Too many requests |
EXECUTION_FAILED | Workflow execution failed |
TIMEOUT | Request timeout |
INTERNAL_ERROR | Internal server error |
Rate Limiting
The API implements rate limiting to ensure fair usage:
- Default: 100 requests per minute per IP
- Authenticated: 1000 requests per minute per user
- Enterprise: Custom limits
Rate limit headers are included in all responses:
1X-RateLimit-Limit: 10002X-RateLimit-Remaining: 9993X-RateLimit-Reset: 1704632400When rate limited:
1{2 "error": {3 "code": "RATE_LIMIT_EXCEEDED",4 "message": "Rate limit exceeded. Try again in 45 seconds.",5 "retry_after": 456 }7}Pagination
List endpoints support pagination:
Request:
1GET /api/v1/executions?limit=50&offset=100Response:
1{2 "executions": [...],3 "total": 500,4 "limit": 50,5 "offset": 100,6 "has_more": true,7 "next_offset": 1508}Parameters:
limit- Items per page (default: 50, max: 100)offset- Starting position (default: 0)
Next Steps
- API Overview -- Authentication and getting started
- Workflow Endpoints -- Execute, monitor, and manage workflow executions
- Best Practices & Examples -- Usage patterns and code examples