Errors - Swish Docs

When a request fails, the Swish API returns a JSON error response with a consistent structure. The HTTP status code indicates the category of failure, and the response body provides details for debugging.

Error format

All error responses use the same envelope:

{
  "error": {
    "message": "Item not found",
    "error": "Not Found",
    "statusCode": 404,
    "requestId": "123e4567-e89b-12d3-a456-426614174000"
  }
}

Field	Type	Description
`message`	`string`	A human-readable description of what went wrong.
`error`	`string`	The HTTP error type (e.g., `"Not Found"`, `"Bad Request"`).
`statusCode`	`number`	The HTTP status code, matching the response status.
`requestId`	`string`	A unique identifier for the request. Include this when contacting support.

Status codes

Code	Error	Description
`400`	Bad Request	The request body or query parameters are invalid or missing.
`401`	Unauthorized	The `Authorization` header is missing or the token is invalid.
`403`	Forbidden	The token is valid but does not have permission for this operation.
`404`	Not Found	The requested resource does not exist.
`429`	Too Many Requests	You have exceeded the rate limit.
`500`	Internal Server Error	An unexpected error occurred on the server. Retry with backoff.

Handling errors

import { createApiClient } from "@swishapp/api-client/2026-07";

const client = createApiClient({
  authToken: "your-api-token",
});

const result = await client.items.findById("nonexistent-id");

if ("error" in result) {
  console.error(`${result.error.statusCode}: ${result.error.message}`);
  console.error(`Request ID: ${result.error.requestId}`);
} else {
  console.log(result.data);
}

const response = await fetch(
  "https://swish.app/api/2026-07/items/nonexistent-id",
  { headers: { Authorization: "Bearer your-api-token" } },
);

if (!response.ok) {
  const { error } = await response.json();
  console.error(`${error.statusCode}: ${error.message}`);
  console.error(`Request ID: ${error.requestId}`);
}

curl -i https://swish.app/api/2026-07/items/nonexistent-id \
  -H "Authorization: Bearer your-api-token"

# HTTP/1.1 404 Not Found
# {
#   "error": {
#     "message": "Item not found",
#     "error": "Not Found",
#     "statusCode": 404,
#     "requestId": "123e4567-e89b-12d3-a456-426614174000"
#   }
# }

The @swishapp/api-client never throws on API errors. Instead, every response is a union: check for "error" in result to distinguish failures from successful responses.

Request ID

Every response - successful or failed - includes a requestId. When reporting an issue to Swish support, include the request ID so the team can look up the exact request in the logs.