Reference

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

CodeMeaning
200Success
201Created
204No Content
400Bad Request - Invalid input
401Unauthorized - Missing or invalid token
403Forbidden - Insufficient permissions
404Not Found - Resource doesn't exist
409Conflict - Resource already exists
422Unprocessable Entity - Validation failed
429Too Many Requests - Rate limit exceeded
500Internal Server Error
503Service Unavailable

Error Codes

CodeDescription
AUTHENTICATION_REQUIREDMissing authentication
INVALID_TOKENToken is invalid or expired
PERMISSION_DENIEDInsufficient permissions
VALIDATION_ERRORRequest validation failed
RESOURCE_NOT_FOUNDRequested resource not found
RESOURCE_CONFLICTResource already exists
RATE_LIMIT_EXCEEDEDToo many requests
EXECUTION_FAILEDWorkflow execution failed
TIMEOUTRequest timeout
INTERNAL_ERRORInternal 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:

1
X-RateLimit-Limit: 1000
2
X-RateLimit-Remaining: 999
3
X-RateLimit-Reset: 1704632400

When rate limited:

1
{
2
"error": {
3
"code": "RATE_LIMIT_EXCEEDED",
4
"message": "Rate limit exceeded. Try again in 45 seconds.",
5
"retry_after": 45
6
}
7
}

Pagination

List endpoints support pagination:

Request:

1
GET /api/v1/executions?limit=50&offset=100

Response:

1
{
2
"executions": [...],
3
"total": 500,
4
"limit": 50,
5
"offset": 100,
6
"has_more": true,
7
"next_offset": 150
8
}

Parameters:

  • limit - Items per page (default: 50, max: 100)
  • offset - Starting position (default: 0)

Next Steps