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 |
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.stewrd.dev |
service_unavailable | 503 | Compute service is not configured | Check status.stewrd.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.
