API Error Handling

Clients need predictable failures.

Stable Error Contract

{
  "code": "RESOURCE_CONFLICT",
  "message": "This slug is already in use",
  "requestId": "req_01KABC",
  "fields": {
    "slug": "Choose another slug"
  }
}

Expected Errors

400 → malformed request
401 → authentication required
403 → permission denied
404 → resource not found
409 → conflict
422 → validation failure
429 → rate limited

Unexpected Errors

Do not send SQL errors, stack traces, secrets or infrastructure details to public clients.

Request IDs

logger.error({
  event: "create_post_failed",
  requestId,
  userId,
  error
});