API REFERENCE
Error Handling
The API uses standard HTTP status codes and returns structured error objects. The SDK wraps these into typed exceptions for easy handling.
Error Response Format
Error response
{
"error": {
"type": "invalid_request_error",
"code": "missing_required_field",
"message": "The 'model' field is required when creating an agent",
"param": "model",
"requestId": "req_abc123def456"
}
}
HTTP Status Codes
CodeTypeDescription
400invalid_request_errorRequest body is malformed or missing required fields
401authentication_errorAPI key is missing, invalid, or revoked
403permission_errorAPI key lacks required scope for this operation
404not_found_errorThe requested resource does not exist
409conflict_errorResource already exists or state conflict
422validation_errorRequest is well-formed but semantically invalid
429rate_limit_errorToo many requests, retry after delay
500internal_errorUnexpected server error
502upstream_errorModel provider is unavailable
503overloaded_errorService temporarily at capacity
Error Codes
CodeDescription
missing_required_fieldA required field was not provided
invalid_field_valueA field has an invalid value or type
invalid_api_keyThe API key is not valid
expired_api_keyThe API key has expired
insufficient_scopeThe API key lacks the required permission
agent_not_foundThe specified agent ID does not exist
execution_not_foundThe specified execution ID does not exist
agent_pausedCannot execute a paused agent
model_unavailableThe specified model is not available
context_length_exceededInput exceeds the model's context window
tool_timeoutA tool handler did not respond in time
tool_errorA tool handler returned an error
rate_limit_exceededRequest rate limit was exceeded
quota_exceededMonthly request quota was exceeded
SDK Error Handling
TypeScript
import { YourAutomation, APIError, RateLimitError } from "@yourautomation/sdk";
try {
const result = await client.agents.execute(agent.id, {
input: "Hello",
});
} catch (err) {
if (err instanceof RateLimitError) {
console.log("Rate limited. Retry after:", err.retryAfter, "seconds");
await sleep(err.retryAfter * 1000);
// retry...
} else if (err instanceof APIError) {
console.error("API error:", err.code, err.message);
console.error("Request ID:", err.requestId);
} else {
throw err;
}
}
Python
from yourautomation import YourAutomation, APIError, RateLimitError
try:
result = client.agents.execute(agent_id, input="Hello")
except RateLimitError as e:
print(f"Rate limited. Retry after {e.retry_after}s")
time.sleep(e.retry_after)
except APIError as e:
print(f"API error: {e.code} - {e.message}")
print(f"Request ID: {e.request_id}")
Retry Strategy
The SDK includes automatic retries for transient errors (429, 500, 502, 503). Configure the retry behavior:
Retry configuration
const client = new YourAutomation({
apiKey: process.env.YA_API_KEY!,
maxRetries: 3, // retry up to 3 times
retryDelay: 1000, // initial delay in ms
retryBackoff: 2, // exponential backoff multiplier
// Retries: 1s, 2s, 4s
});