Errors
The Alsorn Protocol API uses conventional HTTP status codes and returns structured JSON error bodies so your application can handle failures programmatically.
Error Response Format
Every error response includes a JSON body with a code, a human-readable message, and a unique request_id for debugging.
Error Response
{ "error": { "code": "not_found", "message": "Agent not found", "request_id": "req_abc123" }}Error Codes
The following table lists all error codes returned by the API, along with their HTTP status codes and descriptions.
| Parameter | Type | Required | Description |
|---|---|---|---|
| missing_auth | 401 | optional | No authorization header provided. Include an Authorization: Bearer header with your API key. |
| invalid_auth_format | 401 | optional | Malformed authorization header. The header must follow the format: Authorization: Bearer als_... |
| invalid_api_key | 401 | optional | API key not found or revoked. Verify the key is correct and has not been deleted. |
| revoked_api_key | 401 | optional | API key has been explicitly revoked. Create a new key from the dashboard at /control/keys. |
| forbidden | 403 | optional | Insufficient permissions for this operation. Check that your API key has the required permission level (read, write, or admin). |
| not_found | 404 | optional | The requested resource does not exist. Verify the ID or path is correct. |
| validation_error | 422 | optional | Request body validation failed. Check the error message for details on which fields are invalid or missing. |
| plan_limit_exceeded | 403 | optional | You have exceeded a resource limit for your current plan (e.g., max agents, max transactions). Upgrade your plan to increase limits. |
| rate_limit_exceeded | 429 | optional | Too many requests. Back off and retry after the duration in the Retry-After header. See the Rate Limits guide for details. |
| internal_error | 500 | optional | An unexpected error occurred on the server. Retry the request. If the problem persists, contact support with the request_id. |
Error Handling
The Alsorn SDKs raise typed exceptions for each error category, making it straightforward to handle specific failure modes in your code.
error_handling.py
from alsorn import ( AlsornClient, AuthenticationError, ForbiddenError, NotFoundError, ValidationError, RateLimitError, AlsornAPIError,)
client = AlsornClient(api_key="als_your_api_key")
try: agent = client.agents.get("agnt_abc123")except AuthenticationError: # 401 — invalid or missing API key print("Check your API key")except ForbiddenError: # 403 — insufficient permissions or plan limit exceeded print("Upgrade permissions or plan")except NotFoundError: # 404 — agent does not exist print("Agent not found")except ValidationError as e: # 422 — bad request body print(f"Validation failed: {e.message}")except RateLimitError as e: # 429 — rate limited print(f"Rate limited, retry after {e.retry_after}s")except AlsornAPIError as e: # Catch-all for any other API error print(f"API error {e.code}: {e.message} (request_id: {e.request_id})")