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, without its query string
`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 or a spent on demand allowance. Names the window that closed, the request class, the plan, the limit, the seconds until it reopens, the tier to upgrade to and, for an on demand allowance, the `action`
`aiAllowance`	object	Present on `429` when the workspace has spent the AI calls its plan includes this month. Names the plan, the allowance, the calls used, when it renews 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` and on the `503` an unreachable Redis or database causes, 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, a store URL could not be parsed, a text value contained a NUL character or an unpaired surrogate, the body or query string was nested more than 64 levels deep, the path contained an invalid percent escape such as `%zz` (the web proxy at `/api/backend` answers it with the same envelope), or the body was not valid JSON or could not be decoded
`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, a path id contains a NUL character, or an admin surface is refusing to confirm it exists
`429`	A plan rate limit, an on demand allowance or the monthly AI allowance is spent. `Retry-After` says when it reopens; `rateLimit` or `aiAllowance` names which. 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
`413`	The request body is larger than the 100 KB (102400 bytes) the API reads, counted after any `Content-Encoding` is decoded, or a form body carries more than 1000 parameters. The body is read before authentication, so an oversized request is refused even without a valid credential. The web proxy at `/api/backend` applies the same 102400 bytes to the bytes it receives, whatever their content type or `Content-Encoding`, forwards that header so the API decodes the body and counts the decoded size against its own limit, answers the same envelope as soon as a body passes the limit without reading the rest, and closes the connection
`415`	The body names a charset the API cannot read, or a `Content-Encoding` other than `gzip`, `deflate` or `br`
`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. A store failure answers with a fixed sentence naming the store, and the underlying error is in the API log at warn level. An import, a refresh, a new competitor or keyword suggestions that wait more than 20 seconds for a store answer this too, so the sentence arrives before the web proxy gives up. A market check that waits that long reports the market as unknown instead
`503`	The health endpoint could not reach the database, or Redis could not be reached for a sign in or a store action that must be counted first. `Retry-After` says when to try again. The health `503` also carries `status`, `db`, `redis` and `pipeline`, described in Health checks. See When Redis is unreachable
`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.

A spent AI allowance

When a workspace has used every AI call its plan includes this month, the four AI endpoints answer 429 with an aiAllowance object, and Retry-After counts the seconds until 00:00 UTC on the 1st. What counts as a call is described in AI features.

{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "The monthly AI allowance is spent: 200 of 200 calls used. It renews at 2026-11-01T00:00:00.000Z.",
  "path": "/actions/act_1/explain",
  "timestamp": "2026-10-17T09:12:44.120Z",
  "aiAllowance": {
    "plan": "indie",
    "limit": 200,
    "used": 200,
    "resetsAt": "2026-11-01T00:00:00.000Z",
    "upgradeTo": "ultimate"
  },
  "retryAfterSeconds": 1262836
}

A self hosted instance that sets AI_CALLS_PER_MONTH=0 has turned AI calls off, so the same 429 carries the message This workspace includes no AI calls. and an aiAllowance whose limit is 0. Nothing renews in that case, so waiting does not help until the operator raises the limit. Retry-After is still sent, pointing at the next period, so a client that reads it keeps working.

Validation errors

Every controller input is a DTO validated by a global pipe that refuses any property the DTO does not declare. Two consequences follow.

An unknown property answers 400 with the message property <name> should not exist, so a typo in a field name is refused rather than silently ignored.
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 rejected rather than stripped, a misspelled field fails the request instead of letting it succeed while changing nothing.

Text the database cannot store

PostgreSQL text cannot hold the NUL character (U+0000), so the API refuses it before any query runs, in the path, the query string and the body alike.

A NUL in a path id answers 404 with the message Resource not found, because no id can contain one.
A NUL in a query value or a body field answers 400, and the message names the value, such as note must not contain a NUL character or keywords[1] must not contain a NUL character. When a property name itself holds the character, the message names body or query instead, so the character never travels back in a response.

A JSON body can also carry half of an emoji, written as a lone escape such as \ud83d with no partner. That is not valid Unicode text, so it answers 400 with must be well formed Unicode text. Every other character is accepted, including emoji and the other control characters. Passwords and the one time tokens in confirmation, reset and invitation links are hashed rather than stored, so they are never inspected and may hold any character. A refused request stores nothing.

Nesting depth

No request this API accepts nests more than a few levels, so a body or query string nested more than 64 levels deep, counting every object and array, answers 400 with the message body must not be nested more than 64 levels deep (or query). The limit applies to every field, passwords included, and is checked before validation, so a deeply nested body is refused cheaply instead of exhausting the validator.

What an error never repeats

The path and the message of an unknown route name the path only. The query string is left out on purpose: a client that puts a token in a URL by mistake would otherwise get it back in an error body that its logs, its error reporter or a proxy may keep. The API never reads a credential from a query string. Send a personal token in the Authorization: Bearer header, as described in Authentication. Validation messages name the field that failed and the rule it broke, not the value you sent.

API conventions

What the successful responses look like.

Troubleshooting

The same codes seen from the operator side.

Overview

Endpoints

The envelope

Status codes

A spent AI allowance

Validation errors

Text the database cannot store

Nesting depth

What an error never repeats

API conventions

Troubleshooting

​The envelope

​Status codes

​A spent AI allowance

​Validation errors

​Text the database cannot store

​Nesting depth

​What an error never repeats

​Related

API conventions

Troubleshooting

The envelope

Status codes

A spent AI allowance

Validation errors

Text the database cannot store

Nesting depth

What an error never repeats

Related