All errors return a consistent JSON shape:
{
"error": {
"code": "invalid_api_key",
"message": "Invalid or missing API key. Include your key as: Authorization: Bearer sk-stw_...",
"docs": "https://docs.stewrd.dev/quickstart"
}
}
| Field | Type | Description |
|---|
code | string | Machine-readable error code |
message | string | Human-readable error description |
docs | string | Link to relevant documentation |
Error Codes
| Code | HTTP | Description | Fix |
|---|
invalid_api_key | 401 | Key is missing, malformed, or revoked | Check your Authorization header and key |
invalid_body | 400 | Request body is not valid JSON | Ensure Content-Type is application/json |
missing_message | 400 | The message field is missing or empty | Include a non-empty message in the body |
invalid_capabilities | 400 | Capabilities array contains invalid values | Use valid capability names: chat, research, documents, code, data, files |
capability_not_enabled | 403 | Requested capability is not enabled on the project | Enable the capability in your project settings |
plan_restricted | 403 | Capability requires a paid plan | Upgrade your plan to access this capability |
quota_exceeded | 429 | Monthly request quota exceeded | Upgrade your plan or wait for the next billing cycle |
rate_limited | 429 | Too many requests (60/min limit) | Back off and retry after a short delay |
invalid_tools | 400 | Tool definitions are malformed or exceed limits | Check tool name format, description, and parameter schema. See Custom Tools |
invalid_tool_outputs | 400 | Tool outputs array is malformed | Each output needs tool_call_id (string) and output (string) |
context_expired | 404 | Execution context expired or not found | Submit tool outputs within 5 minutes. Start a new request if expired |
tool_output_too_large | 400 | A single tool output exceeds the 100KB limit | Reduce the output size or summarize the data |
compute_error | 502 | The compute service returned an error | Retry the request; if persistent, contact support |
compute_unavailable | 502 | Failed to reach the compute service | Retry the request; check status.openstatus.dev |
service_unavailable | 503 | Compute service is not configured | Check status.openstatus.dev for outages |
Handling Errors
const response = await fetch('https://api.stewrd.dev/v1/agent', {
method: 'POST',
headers: {
'Authorization': `Bearer ${STEWRD_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ message: 'Hello' }),
})
if (!response.ok) {
const { error } = await response.json()
console.error(`[${error.code}] ${error.message}`)
if (error.code === 'rate_limited') {
// Wait and retry
await new Promise(r => setTimeout(r, 2000))
}
}
All error responses include a docs field with a direct link to the relevant documentation page. Use it to quickly find the fix.
