JSON format
code and message are at the root. field and details are optional. There is no error.code wrapper. Branch on code, not a literal message or its language. A proxy may return HTML or another body: check HTTP status first.
HTTP statuses
The HTTP status names below remain unchanged. Explanations are translated; API identifiers are preserved.Causes and recovery
400 Bad Request
missing_field, invalid_format, unknown_parameter, invalid_base, invalid_against. Correct the input; do not retry the same request.
401 Unauthorized
invalid_api_key or key_revoked. Check the server credential.
402 Payment Required
feature_not_in_plan: inspect details.feature and details.current_plan. This is a plan restriction, not a transient failure.
403 Forbidden
email_not_verified, account_inactive, endpoint_disabled or history_out_of_retention. Resolve the stated cause without a retry loop.
404 Not Found
resource_not_found, bank_not_found or bcv_snapshot_unavailable, depending on the endpoint. Check resource, path and coverage.
406 Not Acceptable
format_not_available: use JSON or XML when CSV cannot represent multiple collections.
422 Unprocessable Entity
reference_unavailable, compared_unavailable or no_route with an age filter. Do not invent a result; apply your explicit unavailability policy.
429 Too Many Requests
rate_limit_exceeded: distinguish burst, monthly or missing scope. Follow quotas and limits.
500 Internal Server Error
internal_error: internal failure. For GET, use bounded retries with backoff and an overall deadline.
502 Bad Gateway
May originate from a source or proxy. Preserve the status even if the body is not JSON; bound GET retries.503 Service Unavailable
Service or data unavailable; may includeservice_unavailable. Do not automatically repeat a POST with an uncertain outcome.
Report a failure
Include the path, UTC time, status andcode, without keys or secrets, when contacting support. Also check service status.