> ## Documentation Index
> Fetch the complete documentation index at: https://agentref.co/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```json theme={null}
{
  "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

<CodeGroup>
  ```javascript Node.js theme={null}
  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)
    }
  }
  ```

  ```python Python theme={null}
  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}")
  ```
</CodeGroup>

## 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

<CodeGroup>
  ```javascript Node.js theme={null}
  // The AgentRef SDK handles retries automatically
  const client = new AgentRef({
    apiKey: 'ak_live_YOUR_KEY',
    maxRetries: 3
  })
  ```

  ```python Python theme={null}
  # The AgentRef SDK handles retries automatically
  client = AgentRef(
      api_key="ak_live_YOUR_KEY",
      max_retries=3
  )
  ```

  ```bash cURL theme={null}
  # 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
  ```
</CodeGroup>