Error Reference

All Angareion API errors return a standard envelope. Use the request_id field when contacting support, and the code field to distinguish error types programmatically.

Standard Envelope

{
  "error": {
    "code": "validation_failed",
    "message": "Event type must match pattern '{domain}.{action}'",
    "request_id": "req_01H7abc...",
    "details": {
      "field": "type",
      "value": "invalid",
      "expected": "^[a-z]+\\.[a-z]+(\\.[a-z]+)*$",
      "example": "order.created"
    }
  }
}

The details object is error-specific — see each code below.

validation_failed

HTTP status: 400 SDK exception: Python ValidationError / TypeScript ValidationError

Cause. The request body or a query parameter failed schema validation. The payload was syntactically valid JSON, but a field was missing, of the wrong type, or violated a format constraint (regex, enum, range).

Fix. Inspect details.field, details.value, and details.expected to identify the offending field. Correct the input and retry. See the Authentication guide for canonical request shapes.

Example envelope:

{
  "error": {
    "code": "validation_failed",
    "message": "Event type must match pattern '{domain}.{action}'",
    "request_id": "req_01H7abc123",
    "details": {
      "field": "type",
      "value": "invalid",
      "expected": "^[a-z]+\\.[a-z]+(\\.[a-z]+)*$",
      "example": "order.created"
    }
  }
}

invalid_event

HTTP status: 400 SDK exception: Python ValidationError / TypeScript ValidationError

Cause. The event envelope structure is malformed — a required CloudEvents field (type, subject, source, data) is missing or has the wrong shape. This is distinct from validation_failed because the error is at the envelope layer, not the field layer.

Fix. Conform to the event envelope contract documented in the Messaging guide. Confirm that type, subject, source, and data are all present and that type follows the {domain}.{action} pattern.

Example envelope:

{
  "error": {
    "code": "invalid_event",
    "message": "Event envelope missing required field 'subject'",
    "request_id": "req_01H7def456",
    "details": {
      "field": "subject",
      "value": null,
      "expected": "non-empty string"
    }
  }
}

authentication_failed

HTTP status: 401 SDK exception: Python AuthenticationError / TypeScript AuthenticationError

Cause. The Bearer token is missing, malformed, expired, or revoked. The Angareion API requires a valid JWT on every request; the JWT is obtained by exchanging an API key via POST /auth/token.

Fix. Re-exchange the API key for a fresh JWT — see the Authentication guide. If the original API key has been revoked, rotate to a new key first.

Example envelope:

{
  "error": {
    "code": "authentication_failed",
    "message": "Bearer token expired",
    "request_id": "req_01H7ghi789",
    "details": {}
  }
}

insufficient_scope

HTTP status: 403 SDK exception: Python AuthorizationError / TypeScript AuthorizationError

Cause. The Bearer token is valid, but the API key it was issued from lacks the scope required for this endpoint. Scopes are set when the API key is created and are inherited by every JWT issued from that key.

Fix. Request a token with broader scope or contact your tenant administrator to issue an API key with the required scope. Check details.required_scope for the exact scope name.

Example envelope:

{
  "error": {
    "code": "insufficient_scope",
    "message": "Endpoint requires scope 'memories:write'",
    "request_id": "req_01H7jkl012",
    "details": {
      "required_scope": "memories:write"
    }
  }
}

not_found

HTTP status: 404 SDK exception: Python NotFoundError / TypeScript NotFoundError

Cause. The resource identified by the URL path does not exist, or it exists in a different tenant the requesting agent does not have access to. Angareion does not distinguish "doesn't exist" from "exists but you can't see it" to avoid leaking tenant-boundary information.

Fix. Verify the resource ID is correct and that the requesting agent belongs to the same tenant as the resource owner. List operations (GET /agents, GET /memories) confirm what's reachable.

Example envelope:

{
  "error": {
    "code": "not_found",
    "message": "Memory mem_01H... not found",
    "request_id": "req_01H7mno345",
    "details": {
      "resource_type": "memory",
      "resource_id": "mem_01H..."
    }
  }
}

conflict

HTTP status: 409 SDK exception: Python ConflictError / TypeScript ConflictError

Cause. An idempotency key was reused with a different request body, or a uniqueness constraint was violated (e.g., creating a webhook with an already-registered source). Angareion's idempotency model is "same key + same body = same result; same key + different body = conflict."

Fix. Use a fresh idempotency key for new operations. To recover the original result, fetch the existing resource by its known ID. Check details.idempotency_key and details.existing_resource_id.

Example envelope:

{
  "error": {
    "code": "conflict",
    "message": "Idempotency key already used with a different payload",
    "request_id": "req_01H7pqr678",
    "details": {
      "idempotency_key": "client-key-abc",
      "existing_resource_id": "evt_01H..."
    }
  }
}

payload_too_large

HTTP status: 413 SDK exception: Python PayloadTooLargeError / TypeScript PayloadTooLargeError

Cause. The request body exceeded a per-endpoint size limit. Typical limits: 1 MB for events (POST /events), 10 MB for memories (POST /memories). The limit is enforced at the API gateway before any business logic runs.

Fix. Split the payload into multiple smaller requests, or reduce the payload size (e.g., trim memory content, store large blobs in object storage and reference by URL). details.actual_size and details.max_size are reported in bytes.

Example envelope:

{
  "error": {
    "code": "payload_too_large",
    "message": "Event payload exceeds 1 MB limit",
    "request_id": "req_01H7stu901",
    "details": {
      "actual_size": 1572864,
      "max_size": 1048576
    }
  }
}

business_rule_violation

HTTP status: 422 SDK exception: Python BusinessError / TypeScript BusinessError

Cause. The request was syntactically valid (passed schema validation) but violates a domain rule. Examples: an interest pattern that conflicts with another interest on the same agent, promoting a memory to a type that doesn't allow promotion, sending an event whose subject pattern doesn't match the sender's identity.

Fix. Read details.rule for the rule that was violated and details.message for the human-readable explanation. Adjust the input to satisfy the rule.

Example envelope:

{
  "error": {
    "code": "business_rule_violation",
    "message": "Interest pattern conflicts with existing interest int_01H...",
    "request_id": "req_01H7vwx234",
    "details": {
      "rule": "interest.unique_pattern_per_agent",
      "conflicting_interest_id": "int_01H..."
    }
  }
}

rate_limited

HTTP status: 429 SDK exception: Python RateLimitError / TypeScript RateLimitError

Cause. The agent or tenant has exceeded its request rate limit. Limits are enforced per-agent and per-tenant on a sliding window. The response includes a Retry-After header indicating how many seconds to wait before retrying.

Fix. Honor the Retry-After header. The official Angareion SDKs auto-retry rate-limited requests with exponential backoff and jitter. If you're hitting limits regularly, contact support to discuss higher tiers.

Example envelope:

{
  "error": {
    "code": "rate_limited",
    "message": "Per-agent rate limit exceeded",
    "request_id": "req_01H7yza567",
    "details": {
      "retry_after_seconds": 12,
      "limit": 100,
      "window_seconds": 60
    }
  }
}

internal_error

HTTP status: 500 SDK exception: Python ServerError / TypeScript ServerError

Cause. An unexpected server error occurred. The request was received and may have been partially processed, but the response could not be completed normally. These errors are safe to retry with the same idempotency key — Angareion's idempotency layer prevents duplicate side effects.

Fix. Retry the request with the same idempotency key. If the error persists across multiple retries, contact support and include the request_id from the response — Angareion correlates request IDs with internal traces.

Example envelope:

{
  "error": {
    "code": "internal_error",
    "message": "Unexpected error processing request",
    "request_id": "req_01H7bcd890",
    "details": {}
  }
}

service_unavailable

HTTP status: 503 SDK exception: Python ServiceUnavailableError / TypeScript ServiceUnavailableError

Cause. The service is temporarily refusing traffic — typically backpressure (a downstream component is overloaded) or a planned maintenance window. The response includes a Retry-After header.

Fix. Honor the Retry-After header and retry. Angareion SDKs auto-retry with exponential backoff. If maintenance is in progress, the status page (status.angareion.com — coming Phase 02) will show the active incident.

Example envelope:

{
  "error": {
    "code": "service_unavailable",
    "message": "Service is temporarily unavailable due to backpressure",
    "request_id": "req_01H7efg123",
    "details": {
      "retry_after_seconds": 30
    }
  }
}

Standard Envelope​

validation_failed​

invalid_event​

authentication_failed​

insufficient_scope​

not_found​

conflict​

payload_too_large​

business_rule_violation​

rate_limited​

internal_error​

service_unavailable​

Standard Envelope

validation_failed

invalid_event

authentication_failed

insufficient_scope

not_found

conflict

payload_too_large

business_rule_violation

rate_limited

internal_error

service_unavailable