Developer›Errors

Errors.

Every error returns a structured JSON response with a machine-readable code and a human-readable message. Every error includes a request_id you can cite in support.

Error shape

error.json

{
  "error": {
    "type": "invalid_request",
    "code": "settlement_wallet_unverified",
    "message": "The settlement wallet has not completed verification.",
    "param": "settlement.wallet",
    "doc_url": "https://opensettle.com/docs/errors#settlement_wallet_unverified",
    "request_id": "req_01HGKM4Z7WQ4X"
  }
}

Error types

`invalid_request`

The request was malformed, missing parameters, or referenced a resource that doesn't exist.

parameter_missingA required parameter was omitted.
parameter_invalidThe value of a parameter violated its constraints.
resource_missingThe referenced customer, subscription, or wallet could not be found.
settlement_wallet_unverifiedThe settlement wallet has not completed verification.
idempotency_key_in_useAn in-flight request with this idempotency key is still being processed.

`authentication`

Authentication or authorization failed.

api_key_missingNo API key was provided on the request.
api_key_invalidThe API key is unrecognized or has been rotated.
api_key_mode_mismatchYou used a test-mode key to operate on a live-mode resource.

`settlement`

On-chain settlement could not complete.

insufficient_allowanceThe customer's ERC-20 allowance is lower than the charge amount.
allowance_revokedThe customer revoked their spending authorization.
chain_congestedThe chain is too congested for cost-effective settlement. Retries automatically.
sanctions_hitThe destination wallet matches an OFAC-sanctioned address.

`rate_limit`

You exceeded the allowed request rate for your plan.

rate_limitedSlow down and honor the Retry-After header.

`api_error`

An unexpected error on OpenSettle's side. Our team is paged automatically.

internal_errorSomething went wrong on our side. The request_id is the key to diagnosing.

API reference Webhooks