Documentation Index
Fetch the complete documentation index at: https://docs.lasscyber.com/llms.txt
Use this file to discover all available pages before exploring further.
The Agnes API returns errors with a consistent JSON envelope so client
applications and SDKs can parse them programmatically. This page is the
overview; every canonical code has a dedicated page under
errors that you can link to from your own
operational runbooks.
If you are using one of the official SDKs
(agnes-security or
@lasscyber/agnes-security),
all of this is parsed for you and surfaced as typed exceptions; this
page is the underlying wire contract.
The envelope
{
"detail": "You have exceeded your limit of 100 requests per minute.",
"code": "rate_limit_exceeded",
"request_id": "5b3f6c7e-7d24-4d40-9b12-3a59c01c6e91",
"doc_url": "https://docs.lasscyber.com/errors/rate_limit_exceeded"
}
| Field | Type | Description |
|---|
detail | string, object, or array | Human-readable message. For HTTP 422 this is an array of {loc, msg, type} validation items. Some routes return a structured object with extra context (e.g. analyzer_unavailable 503 includes analyzer and upstream_status). |
code | string | Canonical, snake_case error code. Stable across releases. |
request_id | string | Echo of the X-Request-ID response header. Quote this when filing support tickets. |
doc_url | string (URL) | Documentation page for this error code (one of the pages in this section). |
Standard headers on error responses
| Header | When | What it means |
|---|
X-Request-ID | Always | Unique ID for the request. Use it when filing a support ticket. |
Retry-After | 429, 503 | Seconds to wait before retrying. SDKs honour this automatically. |
X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset | 200, 429 | Current rate-limit window state. |
X-Billing-Status, X-Billing-Message, X-Subscription-Status, X-Grace-Days-Remaining | 402, sometimes 200 | Subscription health for the calling tenant. |
Validation errors (422)
When a request body fails Pydantic validation, the API returns HTTP
422 with detail as an array of items, matching FastAPI’s
standard:
{
"detail": [
{
"loc": ["body", "max_tokens"],
"msg": "Field required",
"type": "missing"
}
],
"code": "validation_error",
"request_id": "...",
"doc_url": "https://docs.lasscyber.com/errors/validation_error"
}
ValidationError with a field_errors map
(Python) or fieldErrors (TypeScript) that walks the array for you.
Canonical error codes
All codes are stable across minor releases. Adding a new code is a
non-breaking change; renaming or removing a code is a breaking change
and ships with a coordinated SDK release.
| Code | HTTP | When | Retry? |
|---|
bad_request | 400 | Malformed payload, unparseable JSON, schema violation outside Pydantic. | No, fix the request. |
validation_error | 422 | Pydantic / FastAPI request validation failure. | No, fix the request. |
unauthorized | 401 | Missing, expired, or invalid credentials. | No, refresh credentials and retry. |
forbidden | 403 | Authenticated but not authorised for this resource. | No, request access. |
email_not_verified | 403 | JWT user has not verified their email. | No, verify your email. |
not_found | 404 | Resource does not exist or is not visible to this tenant. | No. |
method_not_allowed | 405 | HTTP method not supported on this path. | No. |
idempotency_conflict | 409 | Duplicate Idempotency-Key with a conflicting request body. | No, change the key. |
payload_too_large | 413 | Request body or token count exceeds the configured cap. | No, send a smaller payload. |
unsupported_api_version | 400 / 410 | The Agnes-Version header is older than the minimum supported version. | No, upgrade your SDK or pin a newer version. |
rate_limit_exceeded | 429 | Tenant has exceeded its per-minute or per-month request budget. | Yes, after Retry-After seconds. |
billing_required | 402 | Subscription is past due or in a state that blocks API access. | After resolving billing. |
billing_grace_period | 402 / 403 | Subscription has lapsed but is still inside the grace period. | Yes, but renew before grace expires. |
analyzer_unavailable | 503 | A specific analyzer’s upstream is degraded. | Yes, after Retry-After. SDKs retry automatically. |
service_unavailable | 503 | Generic temporary unavailability. | Yes, with backoff. |
internal_error | 500 | Unexpected server-side failure. Operators are paged automatically. | Optional retry. Quote request_id. |
Retry guidance
Service status
For real-time API health and incident history, see
status.lasscyber.com. Subscribe via
email or Slack to receive notifications when an incident opens or
resolves.
If you are experiencing widespread issues that are not yet reflected
on the status page, file a support ticket from
agnes.lasscyber.com/support and
include a recent request_id.
