Errors

{
  "code": "NOT_FOUND",
  "message": "Document not found",
  "userMessage": "Dokumentet hittades inte.",
  "requestId": "req_V1StGXR8Z5jdHi6BmyT2",
  "resource": "document"
}

​

Handle an error

1. Branch on code. The list of codes is closed, so you can handle each code you care about and treat the rest as a failure.
2. Show userMessage to your users, if you show them anything. Don’t show message, which is written for developers.
3. Log requestId with every failed request.

type SajnError = {
  code: string;
  message: string;
  userMessage: string;
  requestId: string;
  resource?: string | null;
  issues?: { path: string; code: string; message: string }[];
};

class SajnApiError extends Error {
  constructor(
    readonly status: number,
    readonly body: SajnError,
  ) {
    super(`${body.code}: ${body.message} (${body.requestId})`);
  }
}

async function sajnFetch<T>(path: string, init: RequestInit = {}): Promise<T> {
  const response = await fetch(`https://app.sajn.se/api/v1${path}`, {
    ...init,
    headers: {
      Authorization: `Bearer ${process.env.SAJN_API_KEY}`,
      'Sajn-Version': '2026-10',
      ...init.headers,
    },
  });

  if (!response.ok) {
    throw new SajnApiError(response.status, (await response.json()) as SajnError);
  }

  return (await response.json()) as T;
}

try {
  await sajnFetch('/documents/cm4k2x9p10001abcd1234efgh');
} catch (error) {
  if (error instanceof SajnApiError && error.body.code === 'NOT_FOUND') {
    console.log(`No ${error.body.resource ?? 'resource'} with that ID`);
  } else {
    throw error;
  }
}

​

Validation errors

{
  "code": "VALIDATION_FAILED",
  "message": "Invalid email address",
  "userMessage": "Förfrågan innehåller ogiltiga värden.",
  "requestId": "req_V1StGXR8Z5jdHi6BmyT2",
  "issues": [
    {
      "path": "parties.0.email",
      "code": "INVALID_FORMAT",
      "message": "Invalid email address"
    }
  ]
}

• path: the dotted path to the invalid value in the body, the query string, or the path parameters, such as parties.0.email. For a header, it’s the header name, such as Idempotency-Key. It’s empty for a problem with the whole request, such as an unknown query parameter.
• code: one of INVALID_TYPE, INVALID_FORMAT, INVALID_VALUE, TOO_SMALL, TOO_BIG, or UNRECOGNIZED_KEY.
• message: a description of the problem, in English, for developers.

​

Authentication and permission errors

• 401 UNAUTHORIZED means only that the token is missing, invalid, expired, or revoked. Check the API key, or refresh the OAuth access token. For more information, see Refresh the access token.
• 403 means that the token is valid, but the operation isn’t allowed. The code tells you why:
  • PERMISSION_DENIED: the user’s workspace role lacks a permission the operation requires, or the endpoint isn’t available to OAuth apps.
  • INSUFFICIENT_SCOPE: the OAuth token wasn’t granted a scope the operation requires. The body lists requiredScopes and grantedScopes. For more information, see Scopes.
  • PLAN_REQUIRED: the organization’s plan doesn’t include API access or the feature.
  • ACCOUNT_INACTIVE: the organization, the user, or the user’s workspace membership is deactivated or suspended.
  • ACCOUNT_SETUP_REQUIRED: the organization must finish its setup first.
  • LIMIT_EXCEEDED: a plan limit was reached, such as the monthly number of sent documents.

​

Not found errors

• NOT_FOUND: the endpoint exists, but the resource doesn’t, or the token can’t access it. resource names the type of the missing resource, so you can tell a missing document from a missing party on the same path.
• ROUTE_NOT_FOUND: no endpoint matches the method and path in the API version you requested. Check the method and the path. An endpoint that a later version removed also returns ROUTE_NOT_FOUND on that version. For more information, see API versioning.

​

Conflict errors

• INVALID_STATE: the resource’s state doesn’t allow the operation, such as editing a document that was already sent, or downloading a file that isn’t produced yet. Change the state, or wait for it to change, and then retry.
• ALREADY_EXISTS: a resource with the same unique value, such as externalId, already exists.
• APPROVAL_REQUIRED: the operation needs an approval first, such as sending a document that the workspace requires an approval for. To ask for one, see Request approval of a document.
• IDEMPOTENCY_KEY_IN_USE: a request with the same Idempotency-Key is still running. For more information, see Idempotency.

​

Request IDs

​

Retry a failed request

• RATE_LIMITED and IDEMPOTENCY_KEY_IN_USE: wait the number of seconds in the Retry-After response header, and then retry. For a sample, see Retry with backoff.
• DAILY_QUOTA_EXCEEDED: Retry-After can be several hours, so stop sending requests and resume after it. For more information, see Rate limits and quotas.
• UPSTREAM_UNAVAILABLE, INTERNAL_ERROR, and network errors: retry with exponential backoff. To make a retried write request safe, send the same Idempotency-Key header on every attempt. For more information, see Idempotency.
• Every other code: the request fails the same way until you change it, or the state it depends on changes, so don’t retry it unchanged.

​

Error codes