#Error Handling

This document describes the API error response format and common error codes.

#Error Response Format

All error responses follow a unified JSON format:

jsonCopy{
  "statusCode": 400,
  "message": "Error description",
  "error": "Bad Request"
}

For validation errors, more detailed field information may be included:

jsonCopy{
  "statusCode": 400,
  "message": ["name must be a string", "model is required"],
  "error": "Bad Request"
}

#HTTP Status Codes

#Common Error Scenarios

#401 Unauthorized

Cause: API Key is missing or invalid

bashCopy# Missing API Key
curl -X GET "https://your-domain.com/v1/agents"

# Returns
# HTTP 401
# {"statusCode":401,"message":"Unauthorized"}

Solution: Ensure the X-API-Key is correctly included in the request headers.

#400 Bad Request - Project context required

Cause: Missing Project context when creating an Agent

jsonCopy{
  "statusCode": 400,
  "message": "Project context is required to create an agent. Ensure your account has a default project.",
  "error": "Bad Request"
}

Solution: Ensure the API Key is bound to a Project, or specify one via the X-Project-Id request header.

#403 Forbidden

Cause: The API Key does not have sufficient permissions for this operation

jsonCopy{
  "statusCode": 403,
  "message": "Forbidden resource",
  "error": "Forbidden"
}

Solution: Check the API Key's permission level (read/write/admin).

#404 Not Found

Cause: The requested resource does not exist or does not belong to the current organization

jsonCopy{
  "statusCode": 404,
  "message": "Agent agent_xxx not found",
  "error": "Not Found"
}

#429 Too Many Requests

Cause: Request rate exceeds the limit

jsonCopy{
  "statusCode": 429,
  "message": "Too many requests",
  "error": "Too Many Requests"
}

Solution: Reduce request frequency and implement exponential backoff retry. See the Rate Limiting section below.

#Rate Limiting

API requests are subject to rate limits based on your subscription plan, enforced at three levels:

#Plan Limits

#Rate Limit Levels

#Response Headers

Every API response includes the following rate limit headers:

#Rate Limit Error Response

jsonCopy{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Please retry after 45 seconds.",
    "retryAfter": 45
  }
}

#Best Practices

#Retry Strategy

For 429 and 5xx errors, it is recommended to implement exponential backoff retry:

javascriptCopyasync function fetchWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch(url, options);
      if (response.status === 429 || response.status >= 500) {
        const retryAfter = response.headers.get('Retry-After');
        const delay = retryAfter
          ? parseInt(retryAfter) * 1000
          : Math.pow(2, i) * 1000;
        await new Promise(resolve => setTimeout(resolve, delay));
        continue;
      }
      return response;
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      const delay = Math.pow(2, i) * 1000;
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }
}

#Error Logging

It is recommended to log the following information for debugging:

1. Request URL and method
2. HTTP status code
3. Error response body
4. Request timestamp
5. Request ID (if included in the response headers)

#SSE Streaming Error Handling

In streaming chat, errors are delivered via SSE events:

Copydata: {"error":"Tool execution failed: timeout","sessionId":"sess_xxx"}

data: [DONE]

It is recommended to listen for the error field on the client side and handle it appropriately.