Errors

Every answer from the records API has one shape. A refusal carries a sentence that states the rule and, in almost every case, a code from the API's registry, in screaming snake case. Branch on the code, never on the sentence.

The envelope#

A success:

{ "success": true, "data": { "...": "the answer" }, "message": "optional" }

A refusal:

{
  "success": false,
  "error": {
    "statusCode": 422,
    "code": "RECORD_TITLE_TOO_LONG",
    "message": "A title fits in 120 characters.",
    "timestamp": "2026-10-05T14:09:48.102Z",
    "path": "/api/v1/records/machine-action-record/eval-run-4417/transitions"
  }
}

Every answer that names a wait, a 202 IDEMPOTENCY_PENDING and every 429, carries retryAfterSeconds in error and the same number in a Retry-After header. The history route and the disclosure-source route return their files as the body, without the envelope.

Two refusals carry no code: a missing, unknown, or disabled key answers 401, and a body the API cannot read (a field missing or of the wrong type, or a field the route does not take) answers 400 with the validator's sentence.

A sentence that would name a key or a token reaches you as "An error occurred while processing your request.", with its code unchanged. That is one more reason to branch on the code.

Codes#

Keys and workspaces#

Writing an entry#

The three amendment and reference refusals add a second sentence naming the entry, such as which entry of the record is the latest committed.

After the write was queued#

These reach you as record.failed at your webhook and as status: failed with the code in the history, never in the write's own answer.

Any other entry that queued and did not commit carries the sentence "This entry did not commit. Nothing was written, and your earlier entries are unchanged."

Reading#

Sharing#

What to retry#

The SDKs retry a timeout, a dropped connection, a 408, a 429, and a 500, 502, 503 or 504 themselves, twice by default, waiting exactly the seconds a 429 names. A 202 they hand back to you, with its retryAfterSeconds, for your code to send again. Bound any loop of your own by attempts and by time.

Reading an error from code#

Both SDKs raise a PacSpaceError carrying the status, a code, and the API's sentence. For a refusal with status 400, 403, 409, 410, 413, 422 or 500, the code is the API's code, exactly. For 401, 402, 404, 412, 429 and 503, each SDK raises its own typed error, such as RateLimitError for a 429, and the code it carries is the SDK's own name for that error; the API's code is not passed on. On those, branch on the status and read the API's sentence in the message.

import { PacSpace, PacSpaceError } from '@pacspace-io/sdk';

const pac = new PacSpace({ apiKey: process.env.PACSPACE_API_KEY! });

try {
  await pac.records.emit({
    record: 'eval-run-4417',
    title: 'Agent ran a shell command that reached outside the test environment',
    kind: 'tool-call',
    occurredAt: '2026-10-05T14:09:47Z',
    actorId: 'agent-7',
    payloads: [ref],                         // from fingerprint(), as in the quick start
    idempotencyKey: 'eval-run-4417:step-2',
  });
} catch (err) {
  if (!(err instanceof PacSpaceError)) throw err;
  console.error(err.statusCode, err.code, err.message);
  // a title over 120 characters: 422 RECORD_TITLE_TOO_LONG A title fits in 120 characters.
}