Errors

Anchor uses conventional HTTP response codes to indicate the success or failure of an API request. In general:

Codes in the 2xx range indicate success.
Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.).
Codes in the 5xx range indicate an error with Anchor's servers (these are rare).

HTTP Status Code Summary

Status Code	Name	Description
`200`	OK	Everything worked as expected.
`400`	Bad Request	The request was unacceptable, often due to missing a required parameter.
`401`	Unauthorized	No valid API key provided.
`402`	Request Failed	The parameters were valid but the request failed.
`403`	Forbidden	The API key doesn't have permissions to perform the request.
`404`	Not Found	The requested resource doesn't exist.
`409`	Conflict	The request conflicts with another request (perhaps due to using the same idempotent key).
`424`	External Dependency Failed	The request couldn't be completed due to a failure in a dependency external to Anchor.
`429`	Too Many Requests	Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.
`500, 502, 503, 504`	Server Errors	Something went wrong on Anchor's end. (These are rare.)

Error Response Format

Error responses follow this format:

{
  "error": "Bad Request",
  "message": "Invalid request body",
  "code": "invalid_request",
  "param": "workspaceId"
}

Error Attributes

error - A short string indicating the error type
message - A human-readable message providing more details about the error
code - An error code that briefly explains the error reported
param - If the error is parameter-specific, the parameter related to the error

Error Types

Type	Description
`api_error`	API errors cover any other type of problem (e.g., a temporary problem with Anchor's servers), and are extremely uncommon.
`authentication_error`	Failure to properly authenticate yourself in the request.
`invalid_request_error`	Invalid request errors arise when your request has invalid parameters.
`policy_violation_error`	The request would violate a policy (e.g., trying to store PII when no-pii policy is enabled).
`rate_limit_error`	Too many requests hit the API too quickly.

Handling Errors

Our client libraries raise exceptions for many reasons, such as a failed request, invalid parameters, authentication errors, and network unavailability. We recommend writing code that gracefully handles all possible API exceptions.

Python Example

from anchor import (
    AnchorError,
    AuthenticationError,
    NotFoundError,
    ValidationError,
    PolicyViolationError,
    RateLimitError
)

try:
    result = anchor.data.write(agent.id, "key", "value")
except PolicyViolationError as e:
    print(f"Blocked: {e.message}")
except AuthenticationError:
    print("Invalid API key")
except NotFoundError:
    print("Agent not found")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after}s")

TypeScript Example

import {
  AnchorError,
  AuthenticationError,
  NotFoundError,
  ValidationError,
  PolicyViolationError,
  RateLimitError
} from 'anchorai';

try {
  const result = await anchor.data.write(agent.id, 'key', 'value');
} catch (error) {
  if (error instanceof PolicyViolationError) {
    console.log(`Blocked: ${error.message}`);
  } else if (error instanceof AuthenticationError) {
    console.log('Invalid API key');
  } else if (error instanceof NotFoundError) {
    console.log('Agent not found');
  } else if (error instanceof RateLimitError) {
    console.log(`Rate limited. Retry after ${error.retryAfter}s`);
  }
}