Errors

Errors follow RFC 9457 problem details with a stable code you can branch on.

Shape#

Error responses have the content type application/problem+json. detail is human readable, code is stable, and errors maps fields to messages on validation failures.

422 Unprocessable Entity

{
  "type": "https://api.rubikyt.com/problems/validation",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more fields are invalid.",
  "code": "validation",
  "errors": {
    "trader.full_name": "is required",
    "window_hours": "must be between 1 and 168"
  }
}

Problem type

type Problem = {
  type: string;
  title: string;
  status: number;
  detail?: string;
  code?: string;
  errors?: Record<string, string>;
};

Codes#

Status	Code	Meaning
401	`unauthenticated`	Missing, expired or revoked credential.
403	`forbidden`	The key or user lacks the permission for this action.
404	`not_found`	The resource does not exist in your organization.
409	`conflict`	The resource state does not allow the change, for example a decision on an unfinished interview.
410	`expired`	A trader or share link is past its expiry.
422	`validation`	Invalid input, see errors per field.
429	`rate_limited`	Too many requests, slow down and retry.
502	`integration_unreachable`	Your Axcera or custom API could not be reached or answered with an error.

Retry 429, 502 and any 5xx with exponential backoff. Other 4xx errors need a change in the request.