Skip to main content
The AgentRef API uses standard HTTP status codes and returns structured error responses.

​
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"
  }
}
FieldTypeDescription
error.codestringMachine-readable error code
error.messagestringHuman-readable description
error.detailsobjectAdditional context (e.g., validation errors)
meta.requestIdstringUnique request ID for debugging

​
HTTP Status Codes

StatusCodeDescription
400BAD_REQUESTInvalid request parameters or body
401UNAUTHORIZEDMissing or invalid API key
403FORBIDDENNot allowed to access this resource
403INSUFFICIENT_SCOPEAPI key missing required scope
404NOT_FOUNDResource not found
409CONFLICTOperation conflicts with existing data
409IDEMPOTENCY_KEY_REUSEDIdempotency key used with different input
422VALIDATION_ERRORRequest body fails validation
429RATE_LIMITEDToo many requests
500INTERNAL_ERRORSomething went wrong on our side

​
Error Handling Example

import AgentRef from 'agentref'

const client = new AgentRef({ apiKey: 'ak_live_YOUR_KEY' })

try {
  const program = await client.programs.get('nonexistent')
} catch (error) {
  if (error instanceof AgentRef.NotFoundError) {
    console.log('Program not found')
  } else if (error instanceof AgentRef.RateLimitError) {
    console.log('Rate limited, retry after:', error.retryAfter)
  } else if (error instanceof AgentRef.ForbiddenError) {
    console.log('Insufficient permissions')
  } else {
    console.error('Unexpected error:', error.message)
  }
}

​
Rate Limiting

API requests are rate limited per API key using a sliding window.

​
Rate Limits by Tier

TierRequestsWindow
Unauthenticated101 minute
Free601 minute
Starter601 minute

​
Rate Limit Headers

Every response includes rate limit headers:
HeaderDescription
X-RateLimit-LimitMaximum requests allowed in the window
X-RateLimit-RemainingRequests remaining in the current window
X-RateLimit-ResetUnix timestamp when the window resets
Retry-AfterSeconds 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
})