Skip to main content
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"
}
FieldTypeDescription
detailstring, object, or arrayHuman-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).
codestringCanonical, snake_case error code. Stable across releases.
request_idstringEcho of the X-Request-ID response header. Quote this when filing support tickets.
doc_urlstring (URL)Documentation page for this error code (one of the pages in this section).

​
Standard headers on error responses

HeaderWhenWhat it means
X-Request-IDAlwaysUnique ID for the request. Use it when filing a support ticket.
Retry-After429, 503Seconds to wait before retrying. SDKs honour this automatically.
X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset200, 429Current rate-limit window state.
X-Billing-Status, X-Billing-Message, X-Subscription-Status, X-Grace-Days-Remaining402, sometimes 200Subscription 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"
}
Both SDKs expose these as 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.
CodeHTTPWhenRetry?
bad_request400Malformed payload, unparseable JSON, schema violation outside Pydantic.No, fix the request.
validation_error422Pydantic / FastAPI request validation failure.No, fix the request.
unauthorized401Missing, expired, or invalid credentials.No, refresh credentials and retry.
forbidden403Authenticated but not authorised for this resource.No, request access.
email_not_verified403JWT user has not verified their email.No, verify your email.
not_found404Resource does not exist or is not visible to this tenant.No.
method_not_allowed405HTTP method not supported on this path.No.
idempotency_conflict409Duplicate Idempotency-Key with a conflicting request body.No, change the key.
payload_too_large413Request body or token count exceeds the configured cap.No, send a smaller payload.
unsupported_api_version400 / 410The Agnes-Version header is older than the minimum supported version.No, upgrade your SDK or pin a newer version.
rate_limit_exceeded429Tenant has exceeded its per-minute or per-month request budget.Yes, after Retry-After seconds.
billing_required402Subscription is past due or in a state that blocks API access.After resolving billing.
billing_grace_period402 / 403Subscription has lapsed but is still inside the grace period.Yes, but renew before grace expires.
analyzer_unavailable503A specific analyzer’s upstream is degraded.Yes, after Retry-After. SDKs retry automatically.
service_unavailable503Generic temporary unavailability.Yes, with backoff.
internal_error500Unexpected 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.