Error Response Format
All errors follow the same structure:{
"error": {
"code": "BAD_REQUEST",
"message": "Invalid request. Please check your input",
"details": {}
},
"meta": {
"requestId": "req_abc123"
}
}
| Field | Type | Description |
|---|---|---|
error.code | string | Machine-readable error code |
error.message | string | Human-readable description |
error.details | object | Additional context (e.g., validation errors) |
meta.requestId | string | Unique request ID for debugging |
HTTP Status Codes
| Status | Code | Description |
|---|---|---|
400 | BAD_REQUEST | Invalid request parameters or body |
401 | UNAUTHORIZED | Missing or invalid API key |
403 | FORBIDDEN | Not allowed to access this resource |
403 | INSUFFICIENT_SCOPE | API key missing required scope |
404 | NOT_FOUND | Resource not found |
409 | CONFLICT | Operation conflicts with existing data |
409 | IDEMPOTENCY_KEY_REUSED | Idempotency key used with different input |
422 | VALIDATION_ERROR | Request body fails validation |
429 | RATE_LIMITED | Too many requests |
500 | INTERNAL_ERROR | Something went wrong on our side |
Error Handling Example
import {
AgentRef,
ForbiddenError,
NotFoundError,
RateLimitError,
} from 'agentref'
const client = new AgentRef({ apiKey: 'ak_live_YOUR_KEY' })
try {
const program = await client.programs.get('nonexistent')
} catch (error) {
if (error instanceof NotFoundError) {
console.log('Program not found')
} else if (error instanceof RateLimitError) {
console.log('Rate limited, retry after:', error.retryAfter)
} else if (error instanceof ForbiddenError) {
console.log('Insufficient permissions')
} else {
console.error('Unexpected error:', error.message)
}
}
from agentref import AgentRef
from agentref.errors import NotFoundError, RateLimitError, ForbiddenError
client = AgentRef(api_key="ak_live_YOUR_KEY")
try:
program = client.programs.get("nonexistent")
except NotFoundError:
print("Program not found")
except RateLimitError as e:
print(f"Rate limited, retry after: {e.retry_after}")
except ForbiddenError:
print("Insufficient permissions")
except Exception as e:
print(f"Unexpected error: {e}")
Rate Limiting
API requests are rate limited per API key using a sliding window.Rate Limits by Tier
| Tier | Requests | Window |
|---|---|---|
| Unauthenticated | 10 | 1 minute |
| Free | 60 | 1 minute |
| Starter | 60 | 1 minute |
Rate Limit Headers
Every response includes rate limit headers:| Header | Description |
|---|---|
X-RateLimit-Limit | Maximum requests allowed in the window |
X-RateLimit-Remaining | Requests remaining in the current window |
X-RateLimit-Reset | Unix timestamp when the window resets |
Retry-After | Seconds to wait (only on 429 responses) |
Handling Rate Limits
// The AgentRef SDK handles retries automatically
const client = new AgentRef({
apiKey: 'ak_live_YOUR_KEY',
maxRetries: 3
})
# The AgentRef SDK handles retries automatically
client = AgentRef(
api_key="ak_live_YOUR_KEY",
max_retries=3
)
# Check the Retry-After header on 429 responses
curl -s -D - -H "Authorization: Bearer ak_live_YOUR_KEY" \
https://www.agentref.co/api/v1/programs
# HTTP/2 429
# Retry-After: 12
# X-RateLimit-Remaining: 0