Error responses

Every failure returns the same JSON envelope, whatever produced it. A single exception filter builds it, so a Prisma error, a guard rejection and a validation failure all look alike to a client.

The envelope

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Resource not found",
  "path": "/apps/cl123",
  "timestamp": "2026-07-30T09:12:44.118Z"
}

Field	Type	Meaning
`statusCode`	number	The HTTP status, repeated in the body so a logged payload is self describing
`error`	string	The status name, such as `Bad Request`
`message`	string	A human readable explanation. Multiple validation messages are joined with commas
`path`	string	The request path that failed
`timestamp`	string	UTC ISO 8601 timestamp of the failure
`quota`	object	Present on `403` when a plan limit refused the write. Names the resource, the plan, the limit, the usage and the tier to upgrade to
`entitlement`	object	Present on `402`. Names the plan in force, the trial and renewal dates, the tier to upgrade to and the path to reach it
`rateLimit`	object	Present on `429` from a plan rate limit. Names the window that closed, the request class, the plan, the limit, the seconds until it reopens and the tier to upgrade to
`billing`	object	Present on `409` from a billing route. Names the reason the request was refused and the recovery that clears it, either `portal` or `retry`
`retryAfterSeconds`	number	Present on `429`, mirroring the `Retry-After` header

The shape is ApiErrorEnvelope in @asobeast/shared, so a TypeScript client can import it rather than redeclare it.

Status codes

Status	What causes it in this API
`400`	A DTO failed validation, or a store URL could not be parsed
`401`	The session cookie or personal API token is missing, malformed or revoked. The response carries a `WWW-Authenticate: Bearer realm="asobeast"` challenge
`402`	The workspace is not entitled. Only reachable when `BILLING_ENABLED` is `true`. Reads from a browser session stay open; see Authentication and accounts
`403`	A plan capacity limit refused the write, and the `quota` object names it. Also returned to a suspended workspace, and to a read only token that tried to change something
`404`	The resource does not exist, or an admin surface is refusing to confirm it exists
`429`	A plan rate limit or an on demand allowance is spent. `Retry-After` says when it reopens, and `rateLimit` names the window. See Rate limits and quotas
`409`	A unique constraint was violated, an AI endpoint was called with `OPENAI_API_KEY` unset, or a billing route refused a request the `billing` object explains
`500`	An unhandled exception. The message is generic and the stack is logged server side
`501`	A store that asobeast does not support. Both live stores are supported, so this path stays wired for a future store
`502`	A store request failed upstream, or the web proxy could not reach the API
`503`	The health endpoint could not reach the database
`504`	The web proxy timed out waiting for the API to start answering, bounded by `API_PROXY_TIMEOUT_MS`

Three of these are worth reading twice. A 429 and a 403 with a quota object are different problems. A 429 clears by waiting; a capacity limit does not. See Rate limits and quotas. A 504 is produced by the Next.js proxy rather than by the API, so it appears when the API is slow rather than when a request is invalid. The same proxy returns 502 when it cannot reach the API at all. See Web app configuration. A 404 on /docs or /admin/queues is a deliberate answer rather than a missing route. See The queue dashboard and the OpenAPI surface.

Validation errors

Every controller input is a DTO validated by a global pipe with whitelisting on. Two consequences follow.

An unknown property is stripped rather than accepted, so a typo in a field name is silently ignored rather than misapplied.
A failing field produces a 400 whose message names the field and the rule it broke.

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "country must be a string, country must match /^[a-z]{2}$/ regular expression",
  "path": "/apps/cl123/keywords",
  "timestamp": "2026-07-30T09:14:02.551Z"
}

Because unknown properties are stripped rather than rejected, a request that appears to succeed but changed nothing is usually a misspelled field.

API conventions

What the successful responses look like.

Troubleshooting

The same codes seen from the operator side.

Overview

Endpoints

The envelope

Status codes

Validation errors

API conventions

Troubleshooting

​The envelope

​Status codes

​Validation errors

​Related

API conventions

Troubleshooting

The envelope

Status codes

Validation errors

Related