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": "Invalid request",
"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> | null;
};Codes#
| Status | Code | Meaning |
|---|---|---|
| 400 | validation | Malformed JSON, path parameter or query string. |
| 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, or the global integration sync endpoint has been retired. |
| 405 | method_not_allowed | This path does not accept the HTTP method. |
| 413 | payload_too_large | The request exceeds the endpoint body limit. |
| 415 | unsupported_media_type | Send the content type required by the endpoint. |
| 422 | validation | Invalid input, see errors per field. |
| 429 | rate_limited | Too many requests, slow down and retry. |
| 502 | media_unavailable / identity_unavailable | An upstream media or identity provider failed. |
| 503 | unavailable | A required service is temporarily unavailable or not configured. |
Provider search returns per-integration failures in its errors array while available matches remain usable. Selected-trader retrieval returns an upstream error when a provider fails or ignores scope filters. No partial snapshot is saved.
Integration connection checks return a ConnectionReport with ok: false and check details when the provider fails; inspect that field even on HTTP 200 or 201.
Retry 429, 502 and any 5xx with exponential backoff. Other 4xx errors need a change in the request.