1. API Reference
Kobaru
  • Kobaru.io Gateway API
    • Introduction
      • What is Kobaru?
      • Quick start
      • How x402 works
    • Integration
      • Standard x402 SDK
      • Advanced SDK
      • Transparent proxy integration
      • Direct API integration
    • Core Concepts
      • Available Chains and Assets
      • Payment schemes
      • Security
      • Usage models
      • Access tiers
      • Idempotency
    • Guides
      • Pricing your API
      • Going to Production
      • Testing with devnet
      • Bazaar discovery
      • BITE encryption for SKALE
    • API Reference
      • Error Handling
      • Get Supported Payment Kinds
        GET
      • Verify Payment Authorization
        POST
      • Settle Payment
        POST
    • Discovery
      • List Discovery Resources
    • Transparent Proxy
      • Overview - Transparent Proxy
      • Upstream authentication
      • Troubleshooting
      • Constraints and security
      • Capabilities and routes
      • Domain verification
      • Service setup
    • Effortless MCP
      • Kobaru MCP Overview
      • Wallets
      • CLI reference
      • Setup Template
    • Schemas
      • SupportedResponse
      • ErrorResponse
      • UnauthorizedResponse
      • RateLimitResponse
      • VerifySuccessResponse
      • VerifyErrorResponse
      • SettleSuccessResponse
      • SettleErrorResponse
      • DiscoveryResourceItem
      • ListDiscoveryResourcesResponse
  1. API Reference

Error Handling

Complete reference for all error codes returned by the Kobaru Gateway API.
When an API request fails, Kobaru returns a structured error response with a specific error code. Use this reference to understand what went wrong and how to fix it.

Error response format#

All errors follow a consistent JSON structure:
{
  "isValid": false,
  "invalidReason": "error_code_here",
  "error": "Human-readable error message"
}
FieldTypeDescription
isValidbooleanAlways false for error responses
invalidReasonstringMachine-readable error code from this reference
errorstringHuman-readable error description (optional)
For settlement errors, the response uses a slightly different structure:
{
  "success": false,
  "errorReason": "error_code_here",
  "error": "Human-readable error message"
}

HTTP status codes#

Kobaru maps error codes to appropriate HTTP status codes:
HTTP StatusCategoryWhen Used
400 Bad RequestClient ErrorInvalid request format, missing fields, validation failures
401 UnauthorizedAuthenticationMissing or invalid API key
403 ForbiddenAuthorizationValid API key but insufficient permissions
404 Not FoundResourceRequested resource does not exist
409 ConflictStatePayment busy or unresolved: duplicate_request, settlement_pending, idempotency_conflict
422 Unprocessable EntityValidationRequest is well-formed but semantically invalid
429 Too Many RequestsRate LimitRate limit exceeded (enforced by Kobaru's firewall, not the gateway)
500 Internal Server ErrorServerUnexpected server error
503 Service UnavailableServerTemporarily unavailable, retry after Retry-After: claim_unavailable, rpc_unavailable, bite_unavailable (facilitator); duplicate_request, claim_unavailable, settlement_pending, server_configuration_error, unexpected_verify_error, rpc_unavailable, bite_unavailable (proxy)

Replayed results#

When /verify or /settle returns the stored result of an earlier request for the same payment, the body includes "replayed": true and the response has the header Idempotent-Replayed: true. Fresh results omit both. See Idempotency for how Kobaru identifies a payment and what it guarantees.
A replayed settlement confirms a charge that already happened; it is not a new one. Keep an order/fulfillment record per payment and don't deliver again on a replay you already fulfilled.
A stored success is only returned to a request carrying the same signature as the payment (case-insensitive). Another signature for a known payment is verified again, or answered payment_proof_mismatch if the payment is settled.
Only binding outcomes are replayed: a success, a failure on chain, an expiry, a pending outcome or an attempt in progress. An attempt rejected before anything was broadcast (for example insufficient_funds or a simulation failure) is evaluated again on the next request.

Idempotency and settlement codes (/verify, /settle)#

CodeHTTPRetry-AfterEndpointMeaningWhat to do
duplicate_request4095bothThe same payment is being processed right nowRetry after Retry-After
settlement_pending40930bothA transaction was (or may have been) broadcast and its outcome isn't known yet. On /verify: a settle of this payment is unresolved (the verification is not re-run). transaction is included when knownCheck transaction on chain. Retry after Retry-After: a /settle retry checks the chain first and returns the real outcome when it can. If the chain can't tell, Kobaru keeps checking it in the background and records the outcome, which the next retry returns; a payment still unresolved after about a day is reviewed by hand. Contact support if it persists. Don't deliver or ask for a new payment meanwhile
claim_unavailable5035bothThe payment couldn't be claimed (database unavailable). Nothing was recorded or broadcastRetry after Retry-After
rpc_unavailable5035bothEVM (Base, SKALE): the network's RPC couldn't be reached while reading the token contract (authorization nonce or EIP-712 domain): a transport error or timeout. Nothing was broadcast; the attempt is evaluated again on the next request. evm_contract_not_eip3009 (400) is only returned when the contract itself answered (a revert or empty return data)Retry the same payload after Retry-After
bite_unavailable50310bothSKALE with BITE: the encryption service is unreachable (health check on /verify; encryption on /settle failed with a transport error, timeout or 5xx). Nothing was broadcastRetry the same payload after Retry-After
idempotency_conflict409nonebothThe payment already has a binding outcome with a different payTo or amount. (A different network, scheme or token is a different payment, not a conflict)Don't retry. Use the original requirements or a new payment
payment_proof_mismatch400nonebothThe payment is known, but this request's signature isn't the one it was verified, settled, or first broadcast withTreat as invalid; use the original payload
payment_already_settled400none/verifySettled (same signature). Includes transaction, and payer when knownTreat the payment as used; check your fulfillment record
payment_settlement_failed400none/verifyThe settlement failed for good: reverted on chain, expired without landing, or the payer canceled the authorization. Includes transaction when there was oneDon't deliver; the payer needs a new payment
invalid_exact_evm_payload_signature400nonebothEVM signature invalid, including non-canonical ones the token contract rejects (high s, v not 27/28). On /settle it is rejected before anything is recordedThe client must sign again
invalid_exact_solana_payload_signature400nonebothSolana: a client (non-fee-payer) signature is missing or doesn't verify. On /settle it is rejected before anything is recordedThe client must sign the transaction correctly
invalid_exact_evm_payload_authorization_valid_before / blockhash_expired400none/settleExpired before anything was broadcast: final, replayed with replayed: true on later requestsA new payment is needed
evm_authorization_canceled400none/settleThe payer canceled the EVM authorization on chain (EIP-3009 cancelAuthorization) before it was used, found while resolving a pending settlement: nothing moved and it can never execute. Final, replayed with replayed: true on later requestsDon't deliver; a new payment is needed
A /settle that finds the authorization already used on chain (nonce or signature used, a front-run transaction, "already processed") is not reported as a failure: someone executed it, so the answer is settlement_pending until the outcome is known.

Proxy codes (access.kobaru.io)#

reasonHTTPRetry-AfterMeaningWhat the client should do
duplicate_request5035The same payment is being processed by another request (answered before your API is called)Retry after Retry-After
claim_unavailable5035The payment couldn't be claimed right now. If your API already answered, the use is refundedRetry after Retry-After
server_configuration_error50330The gateway can't process this payment network right now (server-side). Nothing was broadcast; if your API already answered, the use is refundedRetry after Retry-After; don't pay again
unexpected_verify_error5035Verification failed unexpectedly on the server (answered before your API is called)Retry after Retry-After; don't pay again
rpc_unavailable5035The network's RPC couldn't be reached while verifying the payment (answered before your API is called). Nothing was broadcastRetry after Retry-After; don't pay again
bite_unavailable50310SKALE BITE encryption is unreachable (body error Payment encryption temporarily unavailable). Nothing was broadcast; if your API already answered, the use is refundedRetry after Retry-After; don't pay again
settlement_pending50330The settlement has an unknown outcome (transaction when known). Before your API is called, the proxy first tries to resolve it on chainRetry after Retry-After; don't pay again. When it resolves, the retry is served without costing a new use
payment_settlement_failed402noneThe settlement failed for good (on chain, expired, or the authorization was canceled). Other settle rejections keep their own reason (e.g. payment_proof_mismatch, a signature code)Pay again with a new payment
payment_expired402noneThe payment is settled but its quota has lapsed (or was never created)Pay again
payment_already_used402noneA single-use payment was already usedPay again
usage_exhausted402noneThe quota is used upPay again
payment_bound_to_other_route402noneThe payment's quota belongs to the first service route that used itUse it on that route, or pay for this one
payment_proof_mismatch402noneThe signature isn't the one the payment was made withUse the original payload
A 503 from the proxy is never a payment failure: retry after Retry-After, never pay again for it.

General error codes#

These errors apply across all payment networks and endpoints.

Request validation errors#

CodeHTTPDescriptionResolution
invalid_x402_version400The x402Version field is not 2Ensure your request includes "x402Version": 2 in the payload
invalid_payload400Missing or malformed paymentPayloadVerify the payment payload structure matches the x402 v2 specification
invalid_payment_requirements400Missing or invalid paymentRequirementsInclude all required fields: scheme, network, amount, asset, payTo
invalid_network400The specified network is invalid or unsupportedUse a valid CAIP-2 network identifier (e.g., solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp)
unsupported_scheme400The payment scheme is not supportedKobaru currently supports the exact scheme

Capability errors#

CodeHTTPDescriptionResolution
capability_not_enabled400The requested network/scheme/asset combination is not enabled for this clientEnable the capability in your Kobaru Console or contact support

Concurrency errors#

The idempotency and settlement codes (duplicate_request, settlement_pending, claim_unavailable, idempotency_conflict, payment_proof_mismatch, payment_already_settled, payment_settlement_failed, and the signature codes) are listed with their status, Retry-After and retry advice in Idempotency and settlement codes. concurrent_capture_in_progress is no longer returned.

Server errors#

CodeHTTPDescriptionResolution
unexpected_verify_error500An unexpected error occurred during payment verificationRetry the request. If the error persists, contact support
unexpected_settle_error500An unexpected error occurred during payment settlementCheck transaction status on-chain before retrying. Contact support if the error persists
server_configuration_error500The server is missing required configuration. When the network's driver can't be set up, nothing is recorded (a payment with a stored result still gets it: a replay, duplicate_request or settlement_pending). When a driver returns it after the claim (for example Solana without a fee payer: verify fails closed), a rejected REJECTED/FAILED row is written and the payment stays re-evaluableContact Kobaru support. This indicates a server-side configuration issue; the same payload can be retried once it's fixed. The proxy answers 503 (Retry-After: 30), never 402. Also returned when the SKALE BITE encryption service answers /settle with something unusable (4xx, non-JSON body, invalid encryption); an unreachable service is bite_unavailable
rpc_unavailable503EVM: the network's RPC couldn't be reached while reading the token contract. Nothing was broadcastRetry after Retry-After (5). See Idempotency and settlement codes
bite_unavailable503SKALE: the BITE encryption service is unreachable. Nothing was broadcastRetry after Retry-After (10). See Idempotency and settlement codes

Solana-specific error codes#

These errors occur when processing payments on the Solana network.

Amount and recipient errors#

CodeHTTPDescriptionResolution
invalid_exact_solana_payload_authorization_value400The transfer amount does not match the required amountEnsure the transaction transfers exactly the amount specified in paymentRequirements.amount
invalid_exact_solana_payload_recipient_mismatch400The destination address does not match the required payTo addressVerify the transfer is sent to the correct Associated Token Account (ATA) for the payTo wallet
invalid_asset_mismatch400The token mint does not match the required assetUse the correct SPL token mint address specified in paymentRequirements.asset

Transaction format errors#

CodeHTTPDescriptionResolution
invalid_transaction_format400The transaction cannot be decodedEnsure the transaction is a valid base64-encoded Solana transaction
transaction_too_large400The transaction exceeds the maximum allowed sizeReduce the transaction size by removing unnecessary instructions
malformed_instruction400An instruction in the transaction cannot be parsedVerify all instructions use correct program IDs and data formats

Fee payer errors#

CodeHTTPDescriptionResolution
invalid_fee_payer400The transaction fee payer is not the Kobaru facilitatorSet the facilitator's public key as the fee payer. The facilitator covers transaction fees

Compute budget errors#

CodeHTTPDescriptionResolution
missing_compute_budget_limit400Transaction is missing the SetComputeUnitLimit instructionAdd a SetComputeUnitLimit instruction as the first instruction
missing_compute_budget_price400Transaction is missing the SetComputeUnitPrice instructionAdd a SetComputeUnitPrice instruction as the second instruction
invalid_compute_unit_limit400The compute unit limit is invalid or exceeds allowed maximumSet a reasonable compute unit limit (typically 200,000-400,000 for token transfers)
priority_fee_exceeds_limit400The priority fee exceeds the maximum allowed by the facilitatorReduce the priority fee. Maximum is configured by the facilitator (default: 100,000 lamports)

Instruction topology errors#

Kobaru enforces a strict instruction order to prevent transaction manipulation:
CodeHTTPDescriptionResolution
invalid_instruction_count_topology400The transaction has an unexpected number of instructionsTransactions must have exactly 4 instructions (or 5 if creating an ATA)
invalid_instruction_topology_expected_create_ata400Expected a CreateAssociatedTokenAccount instruction but found something elseIf the recipient ATA doesn't exist, include a CreateATA instruction in position 3
invalid_instruction_topology_ata_mismatch400The ATA being created doesn't match the expected recipientEnsure the CreateATA instruction creates an ATA for the correct recipient and mint
missing_transfer_instruction400No SPL token transfer instruction found (e.g. another Token instruction such as ApproveChecked in the transfer slot)Include a TransferChecked instruction as the final instruction
unsupported_token_program400The transfer is not an instruction of the standard SPL Token program (TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA)Use the standard SPL Token program. Token-2022 transfers are answered with unsupported_scheme
Required instruction order:
1.
SetComputeUnitLimit (ComputeBudget program)
2.
SetComputeUnitPrice (ComputeBudget program)
3.
CreateAssociatedTokenAccount or CreateAssociatedTokenAccountIdempotent (optional, if recipient ATA doesn't exist; Associated Token program, System and SPL Token program accounts)
4.
TransferChecked (SPL Token program, 4 accounts: no multisig)
Memo instructions (Memo program) may appear anywhere. Each instruction must match its program, discriminator and data length exactly: trailing bytes are rejected (malformed_instruction).

Security errors#

These errors prevent unauthorized use of the facilitator's resources:
CodeHTTPDescriptionResolution
facilitator_cannot_pay_ata_creation400The transaction attempts to have the facilitator pay for ATA creation rentThe payer (not the facilitator) must pay for ATA creation
facilitator_cannot_be_payer400The transaction source is the facilitator's walletYou cannot transfer tokens from the facilitator's wallet
facilitator_cannot_be_authority400The facilitator is set as the transfer authorityThe payer must be the authority for the token transfer
facilitator_ata_cannot_be_source400The source ATA belongs to the facilitatorYou cannot transfer tokens from the facilitator's token account
facilitator_in_instruction_accounts400The facilitator (fee payer) is listed in an instruction's accountsThe facilitator may only be the fee payer: don't pass its address to any instruction, memo included

Payer validation errors#

CodeHTTPDescriptionResolution
cannot_determine_payer400Unable to determine the transaction payer from the transfer instructionEnsure the transfer instruction has a valid source account
invalid_payer_address_format400The payer address is not a valid Solana public keyUse a valid base58-encoded Solana public key

Memo validation errors#

CodeHTTPDescriptionResolution
missing_required_memo400Transaction is missing a required Memo instructionAdd a Memo instruction for payment attribution
empty_memo400The Memo instruction contains no dataInclude meaningful memo content for payment tracking
memo_too_long400The memo exceeds the maximum allowed lengthReduce memo length (maximum varies by configuration)
invalid_memo_format400The memo format is invalidEnsure the memo follows the required format for payment attribution

Transaction lifecycle errors#

CodeHTTPDescriptionResolution
blockhash_expired400The transaction's recent blockhash has expiredGenerate a new transaction with a fresh blockhash (blockhashes expire after ~60-90 seconds)
transaction_signature_already_used400The network already processed this transaction. Only a settle can hit it, and it is reported as settlement_pending (409), since the transaction was executedCheck the previous result or the transaction on chain
simulation_failed400Transaction simulation failed before submissionCheck that the payer has sufficient SOL for fees and sufficient tokens for the transfer
submission_failed400The transaction was rejected before broadcast, or failed on chain (then transaction is included and the failure is final). A confirmation timeout is reported as settlement_pending insteadWithout transaction: fix the cause and retry. With transaction: a new payment is needed

Settlement errors#

settle_timeout and settle_confirmation_failed are no longer returned: a settlement whose confirmation times out or can't be read is reported as settlement_pending (409, Retry-After: 30, transaction when known). See Idempotency and settlement codes.

Troubleshooting common errors#

simulation_failed#

Symptoms: Transaction verification returns simulation_failed before the transaction is submitted.
Common causes:
1.
Insufficient SOL balance - The payer needs SOL to pay transaction fees (even though the facilitator is the fee payer, simulation may fail if accounts are not properly funded)
2.
Insufficient token balance - The source account doesn't have enough tokens
3.
Invalid account states - One or more accounts in the transaction are in an invalid state
Resolution:

capability_not_enabled#

Symptoms: Request returns capability_not_enabled even though you expect the capability to work.
Common causes:
1.
Capability not configured - The network/scheme/asset combination hasn't been enabled for your account
2.
Wrong network identifier - Using mainnet ID when your account is configured for devnet (or vice versa)
3.
Wrong asset address - Using an incorrect token mint address
Resolution:
1.
Log in to console.kobaru.io
2.
Navigate to Settings > Capabilities
3.
Verify the correct network, scheme, and asset are enabled
4.
For Solana devnet testing, use: solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1
5.
For Solana mainnet, use: solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp

invalid_fee_payer#

Symptoms: Transaction is rejected because the fee payer is incorrect.
Common causes:
1.
Wrong fee payer set - The transaction specifies a fee payer other than the Kobaru facilitator
2.
SDK misconfiguration - The x402 SDK is not correctly configured to use Kobaru as the facilitator
Resolution:
When constructing your transaction, set the fee payer to the Kobaru facilitator's public key. The facilitator public key is returned in the /supported response.

blockhash_expired#

Symptoms: Transaction is rejected because the blockhash has expired.
Common causes:
1.
Stale transaction - The transaction was created too long ago (blockhashes expire after ~60-90 seconds)
2.
Slow client - Network latency caused delays between transaction creation and submission
Resolution:
1.
Create transactions with fresh blockhashes immediately before submission
2.
Use getLatestBlockhash() with the finalized commitment for the most reliable blockhashes
3.
Consider using durable nonces for transactions that need longer validity

duplicate_request#

Symptoms: Request returns duplicate_request when you believe it's a new request.
Common causes:
1.
Retry collision - A previous request with the same signature is still being processed
2.
Reused transaction - The same signed transaction was submitted multiple times
Resolution:
1.
Wait for the original request to complete before retrying
2.
If retrying, the API will return the cached result for the same idempotency key
3.
For new payment attempts, create a new transaction with a fresh blockhash and signature

priority_fee_exceeds_limit#

Symptoms: Transaction is rejected due to excessive priority fees.
Common causes:
1.
Priority fee too high - The compute unit price results in total fees exceeding the facilitator's limit
2.
Automatic fee estimation - Some SDKs automatically set high priority fees during network congestion
Resolution:
The Kobaru facilitator enforces a maximum priority fee (default: 100,000 lamports) to prevent abuse. Calculate your priority fee:
Total Priority Fee = Compute Units * Compute Unit Price / 1,000,000
Reduce either the compute unit limit or the compute unit price to stay within limits.

Error code quick reference#

By category#

Validation errors: invalid_x402_version, invalid_payload, invalid_payment_requirements, invalid_network, unsupported_scheme
Solana amount/recipient: invalid_exact_solana_payload_authorization_value, invalid_exact_solana_payload_recipient_mismatch, invalid_asset_mismatch
Transaction format: invalid_transaction_format, transaction_too_large, malformed_instruction
Compute budget: missing_compute_budget_limit, missing_compute_budget_price, invalid_compute_unit_limit, priority_fee_exceeds_limit
Instruction topology: invalid_instruction_count_topology, invalid_instruction_topology_expected_create_ata, invalid_instruction_topology_ata_mismatch, missing_transfer_instruction, unsupported_token_program
Security: facilitator_cannot_pay_ata_creation, facilitator_cannot_be_payer, facilitator_cannot_be_authority, facilitator_ata_cannot_be_source, facilitator_in_instruction_accounts
Concurrency and idempotency: duplicate_request, settlement_pending, claim_unavailable, idempotency_conflict, payment_already_settled, payment_settlement_failed, payment_proof_mismatch, transaction_signature_already_used
Proxy only: 503 duplicate_request / claim_unavailable / settlement_pending / server_configuration_error / unexpected_verify_error / rpc_unavailable / bite_unavailable; 402 payment_settlement_failed, payment_expired, payment_already_used, payment_bound_to_other_route, usage_exhausted, payment_proof_mismatch
Server: unexpected_verify_error, unexpected_settle_error, server_configuration_error, rpc_unavailable, bite_unavailable (settle_timeout and settle_confirmation_failed are no longer returned)

Getting help#

If you encounter an error not covered in this reference or need additional assistance:
Documentation: docs.kobaru.io
Support: support@kobaru.io
Discord: Join our developer community for real-time help
When contacting support, include:
1.
The full error response (including invalidReason)
2.
Your request payload (redact sensitive information)
3.
The timestamp of the request
4.
Your client ID (available in the Console)
Modified at 2026-10-30 21:41:37
Previous
BITE encryption for SKALE
Next
Get Supported Payment Kinds
Built with