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

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
`402`	The account is not entitled. Only reachable when `BILLING_ENABLED` is `true`
`404`	The resource does not exist, or an admin surface is refusing to confirm it exists
`409`	A unique constraint was violated, or an AI endpoint was called with `OPENAI_API_KEY` unset
`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, bounded by `API_PROXY_TIMEOUT_MS`

Two of these are worth reading twice. 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