Errors & Status Codes

How AuthSpoke reports success and failure — status codes and structured error bodies.

AuthSpoke uses conventional HTTP status codes and returns structured JSON error bodies.

Status codes#

Code	Meaning
`200`	Success.
`201`	Resource created.
`204`	Success, no content (e.g. a delete).
`400`	Malformed request (bad body or path value).
`401`	Authentication failed — e.g. email not verified during registration.
`403`	Forbidden — missing/invalid token, an unlicensed capability, or a provider-only route.
`404`	Resource not found (or not in your tenant).
`500`	Unexpected server error.

Capability and provider denials return a machine-readable body:

{
  "error": "capability_not_licensed",
  "capability": "IDENTITY_FOUNDATION",
  "message": "This capability is not enabled for your tenant."
}

{
  "error": "provider_admin_required",
  "message": "The Provider console is restricted to AuthSpoke support admins."
}

A 403 can mean three different things — branch on the body:

No error field → your bearer token is missing or invalid. Re-authenticate.
capability_not_licensed → the tenant hasn't licensed that SKU. See Capability SKUs.
provider_admin_required → the route is cross-tenant and provider-only. See Provider Console.

A resource that exists in another tenant returns 404 (not 403) — AuthSpoke never confirms the existence of data outside your tenant.