Errors

Error response format, HTTP status codes, and rate limiting.

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"
  }
}

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

Node.js

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)
  }
}

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

Node.js

// The AgentRef SDK handles retries automatically
const client = new AgentRef({
  apiKey: 'ak_live_YOUR_KEY',
  maxRetries: 3
})