Errors

AIUS returns standard HTTP status codes. Error bodies use FastAPI’s detail envelope. There are two shapes you’ll encounter.

Structured errors

Account-side endpoints (auth, 2FA, clients, projects) return a structured detail object with a stable code and a human message:

{
  "detail": {
    "code": "INVALID_CREDENTIALS",
    "message": "Invalid email or password"
  }
}

Always branch on detail.code (stable), not detail.message (may change).

r = httpx.post("https://aius.co/api/v1/login", json=creds)
if r.status_code != 200:
    err = r.json().get("detail", {})
    code = err.get("code") if isinstance(err, dict) else None
    raise RuntimeError(f"login failed: {code} — {r.status_code}")

String errors

Some gateway-level checks (bearer validation, token minting, upstream availability) return detail as a plain string:

{ "detail": "invalid token" }

A robust client should handle both:

detail = r.json().get("detail")
code = detail.get("code") if isinstance(detail, dict) else None
message = detail.get("message") if isinstance(detail, dict) else detail

HTTP status codes

Code	Meaning
`200`	Success
`400`	Bad request — missing/invalid field
`401`	Unauthorized — missing/invalid credential or session
`403`	Forbidden — authenticated but no access to the resource
`404`	Not found
`409`	Conflict — e.g. email already exists, 2FA already enabled
`429`	Rate limited — back off and retry
`500`	Internal error
`503`	Upstream/account service unavailable

Common codes

Authentication & registration

Code	HTTP	Meaning
`MISSING_NAME` / `MISSING_EMAIL` / `MISSING_PASSWORD`	400	A required field was empty
`INVALID_EMAIL`	400	Malformed email
`PASSWORD_TOO_WEAK`	400	Min 8 chars, with a letter, number, and special character
`EMAIL_ALREADY_EXISTS`	409	An account with this email already exists
`INVALID_CREDENTIALS`	401	Wrong email or password
`REGISTRATION_FAILED`	500	Unexpected failure during registration

Two-factor

Code	HTTP	Meaning
`INVALID_CHALLENGE`	401	Expired/invalid 2FA challenge token
`INVALID_CODE`	400 / 401	Wrong TOTP or recovery code
`2FA_ALREADY_ENABLED`	409	2FA is already on for this account
`2FA_NOT_STARTED`	400	Call `/v1/2fa/setup` before `/v1/2fa/enable`
`2FA_NOT_ENABLED`	400	2FA is not enabled for this account

Bearer / tokens

Detail (string)	HTTP	Meaning
`missing bearer token`	401	No `Authorization` header
`invalid authorization header`	401	Header isn’t `Bearer <token>`
`invalid bearer token`	401	Empty token
`invalid token`	401	Unknown or revoked `aius_…` token
`token_name is required`	400	`POST /v1/tokens` needs `token_name`
`no session cookie`	401	`POST /v1/tokens` needs the `__Host-aius_session` cookie

Clients & projects

Code	HTTP	Meaning
`NO_ACCESS`	403	You don’t belong to that client
`NOT_FOUND`	404	Project/resource doesn’t exist
`USER_NOT_FOUND`	404	Identity not resolvable
`MISSING_NAME`	400	Project/client name required

Rate limiting

429 responses indicate you’ve exceeded a per-IP limit (see Overview › Rate limits). Use exponential backoff:

import time, httpx

def with_retry(send, attempts=4):
    for i in range(attempts):
        r = send()
        if r.status_code != 429:
            return r
        time.sleep(2 ** i)
    return r

Service availability

503 with detail like Failed to reach … service means an upstream account service is unreachable. Retry after a short delay.

​Errors

​Structured errors

​String errors

​HTTP status codes

​Common codes

​Authentication & registration

​Two-factor

​Bearer / tokens

​Clients & projects

​Rate limiting

​Service availability