Errors

Every refusal answers a JSON error body with a stable reason code. Branch on the reason, log the request id, and use the table at the end to see every reason a /v1 call can answer.

The error bodyCopy Anchor Link

HTTP/1.1 400 Bad Request
content-type: application/json
x-request-id: 5c1f0d2e-8a4b-4f7e-9c33-0e6b2d1a9f40

{
  "defined": true,
  "code": "invalid_input",
  "status": 400,
  "message": "Input validation failed",
  "data": {
    "issues": [{ "path": ["to", 0, "address"], "message": "Invalid email address" }]
  }
}

Reasons that carry data:

Each operation in the API reference lists the reasons it declares, each with the condition it is answered on.

Handle errorsCopy Anchor Link

• 4xx: the request was refused. Fix it, or act on the reason (reconnect an account on account_reauth_required, wait for export_not_ready).
• 429 and 503: slow down and retry after Retry-After. See Rate limits.
• 500 and 502: the outcome of a write may be unknown. Retry a POST with the same Idempotency-Key; 5xx answers are not stored, so the retry runs the request again. See Idempotency.

The SDK throws every API error as an ORPCError whose code is the reason:

import { isApiError, isDefinedError, safe } from "@workwae/sdk";

// safe() returns [error, data]; isDefinedError() narrows to the reasons this operation declares.
const [error, entry] = await safe(workwae.outbox.get({ accountId, outboxId }));
if (isDefinedError(error) && error.code === "send_not_found") {
  // ...
} else if (error) throw error;

// isApiError() checks for one reason anywhere, and narrows data to that reason's.
try {
  await workwae.outbox.create({ accountId, to: [], text: "hi" });
} catch (error) {
  if (isApiError(error, "invalid_input")) console.log(error.data.issues);
  else if (isApiError(error)) console.log(error.code, error.status, error.requestId);
  else throw error;
}

Request idsCopy Anchor Link

Every answer carries an X-Request-Id header. Quote it when you contact support: it finds the request in Workwae's logs, and it is recorded on the request's audit log entries.

To correlate with your own logs, send your own id: 1 to 128 characters of A-Z a-z 0-9 . _ : -. It is echoed back. Without one, or when yours does not fit, the API generates one.

curl -i "https://api.workwae.com/v1/accounts" \
  -H "Authorization: Bearer $WORKWAE_API_KEY" \
  -H "X-Request-Id: checkout-7f3a91"

Reasons every operation can answerCopy Anchor Link

Besides its own reasons, any operation can answer:

POST operations can also answer invalid_idempotency_key (400), idempotency_key_in_progress (409) and idempotency_key_reused (422). See Idempotency.

Reasons by statusCopy Anchor Link

Every reason a /v1 operation declares, grouped by the one HTTP status it always answers with.