Reference

Response format and errors

The JSend envelope every Backstage API response uses, the shape of an error, and the typed errors the TypeScript SDK throws.

Every Backstage API response, successful or not, uses the same envelope. This page is the envelope itself; to make a call for the first time, follow Your first API call.

Response Format#

All API responses follow the JSend specification:

{
  "status": "success",
  "data": {
    "user": {
      "id": "usr_123abc",
      "email": "your@email.com",
      "firstName": "John",
      "lastName": "Doe",
      "createdAt": "2026-01-01T00:00:00Z"
    }
  }
}

Error Handling#

When things go wrong, the API returns an error response:

{
  "status": "error",
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required",
    "moreInfo": "https://docs.ticketlayer.com/error/UNAUTHORIZED?request=req_01j9x2k3m4n5p6q7r8s9t0v1w2"
  },
  "metadata": {
    "requestId": "req_01j9x2k3m4n5p6q7r8s9t0v1w2"
  }
}

Field	What it is
`error.code`	A stable identifier for what went wrong. Branch on this, never on `message`.
`error.message`	A sentence for a person reading a log. Its wording can change.
`error.moreInfo`	The address of this site's page for the code, `/error/{CODE}`, with the response's request id in the `request` query parameter. Follow it for what the code means and what to do.
`metadata.requestId`	The id of this request. Quote it when you contact support.

Every code the API sends is listed, grouped by HTTP status, at Error codes.

The TypeScript SDK throws typed errors you can catch:

try {
  const user = await client.users.getMe();
} catch (error) {
  if (error.status === 401) {
    console.log('Not authenticated');
  } else if (error.status === 403) {
    console.log('Permission denied');
  } else {
    console.log('API error:', error.message);
  }
}