We collect minimal analytics to understand how the site is used. If you decline, we do not load analytics.
ANCHORGRIDdev
Overview / Errors

Errors

What the Intelligence service raises internally versus what API clients typically see in JSON responses — including behavior for /v1/keys and related auth paths.

Intelligence app

HTTPException envelope

For normal HTTPException, the global handler maps status to a generic JSON body and does not forward route-specific detail (for example Key not found):

{
  "error": {
    "code": "<ENUM>",
    "message": "<short generic string>"
  }
}

Rough mapping:

HTTP
error.code
Typical error.message
401
UNAUTHORIZED
Authentication required
404
NOT_FOUND
Not found
422
UNPROCESSABLE_ENTITY
(check handler — validation uses different path)
500
SERVER_ERROR
An error occurred

Validation

RequestValidationError & bad JSON

For RequestValidationError and invalid JSON shape on POST /v1/keys:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request"
  }
}

Status 422.

ℹ

For DELETE /v1/keys/{id}when the key isn't yours or doesn't exist, the handler still returns 404with the generic "Not found" message. Route-specific detail (e.g. code NOT_FOUND, message Key not found) in routes.py is not what the Intelligence client JSON exposes.

/v1/keys

Errors that matter (by status)

Situations you should model against when integrating key management:

Situation
Status
Notes
No Authorization header / wrong scheme
401
get_current_user: BEARER_TOKEN_REQUIRED-style in code; body genericized as above.
Invalid / expired JWT, bad signature, wrong audience
401
cognito_service.verify_token raises INVALID_TOKEN in detail (genericized in response).
JWKS fetch failure (e.g. Cognito unreachable)
500
AUTH_CONFIG_ERROR in detail in code (genericized).
Invalid JSON body / extra fields policy
422
VALIDATION_ERROR.
Revoke unknown or other user's key_id
404
Generic “Not found” in Intelligence envelope.

402

Not from /v1/keys

402 is raised in job_quota.check_credit_quota when submitting paid-tier / credit-consuming jobs with an API key (for example drawings or specs jobs), e.g. free tier lifetime credits exhausted (FREE_TIER_LIMIT_REACHED in code detail). Creating or listing keys does not call check_credit_quota, so you should not expect 402 on POST, GET, or DELETE /v1/keys in the current code.

429

Not on /v1/keys (current rate-limit list)

RequestRateLimitMiddleware only rate-limits specific POST paths (/v1/documents, /v1/specs/..., /v1/drawings/..., /v1/batches). /v1/keysis not in that set, so those Redis limits don't apply to key minting. (You could still hit other infrastructure limits.)

403

Elsewhere in the API

Not commonly emitted by the keys router itself; the Cognito path uses 401 for auth failures. 403appears elsewhere in the codebase for "forbidden" cases on other routers.

Next steps

ANCHORGRIDdev