Skip to main content

Errors

Every Blank API v2 error is an RFC 9457 Problem Details document served as application/problem+json.
Branch on code, never on detail or title. detail is written for humans and may be reworded. code is part of the contract.
Error responses are always Cache-Control: private, no-store.

Handling errors with the SDK

BlankNetworkError means the outcome is unknown, not that the request failed. If it carries an idempotencyKey, retry the same request with that key rather than assuming anything. The SDK also raises BlankNetworkError when Blank returns a success body that violates the operation’s contract schema, so malformed data never reaches your code. Error responses are checked against the exact operation, HTTP status, code, canonical title, and type URI. If Blank or an intermediary returns anything else, the SDK synthesises invalid_error_response and uses the actual HTTP response status.

Retry guidance by status

Common codes

These can be returned by any operation. One further code is produced by the SDK rather than the API. If a response cannot be parsed as a Problem Details document, the SDK synthesises one so your error handling still receives a consistent shape:

Mutation codes

Returned by any operation that writes.

Pagination and caching

Tokens and market data

Identity, staking, fees, and presales

Price predictions

Prediction eligibility evaluates every independent requirement, including finalized token balance even when the round is closed. The eligibility response can therefore contain both round_not_open and insufficient_balance. A submission returns one primary Problem Details code and places any other failures found during the same evaluation in causes[]; each item has its canonical code, title, detail, and optional context.

Transaction-intent result codes

These codes appear in TransactionIntent.error.code after asynchronous Solana processing. They are not HTTP Problem Details codes.

Operations and transaction intents

Webhooks

Webhook delivery result codes

WebhookDelivery.lastErrorCode is one of the following transport codes, or http_<status> for an HTTP rejection such as http_500:

Reporting a problem

Include the requestId and the code. They identify the exact request in Blank’s telemetry. Never paste an API key, a webhook signing secret, or a signed transaction into a report. For symptom-first guidance, see Troubleshooting.