Error codes

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"
}

Field	Type	Description
isValid	boolean	Always `false` for error responses
invalidReason	string	Machine-readable error code from this reference
error	string	Human-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 Status	Category	When Used
400 Bad Request	Client Error	Invalid request format, missing fields, validation failures
401 Unauthorized	Authentication	Missing or invalid API key
403 Forbidden	Authorization	Valid API key but insufficient permissions
404 Not Found	Resource	Requested resource does not exist
409 Conflict	State	Resource state conflict (e.g., duplicate request)
422 Unprocessable Entity	Validation	Request is well-formed but semantically invalid
429 Too Many Requests	Rate Limit	Rate limit exceeded
500 Internal Server Error	Server	Unexpected server error
503 Service Unavailable	Server	Server temporarily unavailable (missing configuration)

General error codes

These errors apply across all payment networks and endpoints.

Request validation errors

Code	HTTP	Description	Resolution
`invalid_x402_version`	400	The `x402Version` field is not `2`	Ensure your request includes `"x402Version": 2` in the payload
`invalid_payload`	400	Missing or malformed `paymentPayload`	Verify the payment payload structure matches the x402 v2 specification
`invalid_payment_requirements`	400	Missing or invalid `paymentRequirements`	Include all required fields: `scheme`, `network`, `amount`, `asset`, `payTo`
`invalid_network`	400	The specified network is invalid or unsupported	Use a valid CAIP-2 network identifier (e.g., `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp`)
`unsupported_scheme`	400	The payment scheme is not supported	Kobaru currently supports the `exact` scheme

Capability errors

Code	HTTP	Description	Resolution
`capability_not_enabled`	400	The requested network/scheme/asset combination is not enabled for this client	Enable the capability in your Kobaru Console or contact support

Concurrency errors

Code	HTTP	Description	Resolution
`duplicate_request`	409	A request with the same idempotency key is already being processed	Wait for the original request to complete, then retry if needed
`concurrent_capture_in_progress`	409	Another settlement is in progress for this authorization	Wait for the existing settlement to complete

Server errors

Code	HTTP	Description	Resolution
`unexpected_verify_error`	500	An unexpected error occurred during payment verification	Retry the request. If the error persists, contact support
`unexpected_settle_error`	500	An unexpected error occurred during payment settlement	Check transaction status on-chain before retrying. Contact support if the error persists
`server_configuration_error`	503	The server is missing required configuration	Contact Kobaru support. This indicates a server-side configuration issue

Solana-specific error codes

These errors occur when processing payments on the Solana network.

Amount and recipient errors

Code	HTTP	Description	Resolution
`invalid_exact_solana_payload_authorization_value`	400	The transfer amount does not match the required amount	Ensure the transaction transfers exactly the amount specified in `paymentRequirements.amount`
`invalid_exact_solana_payload_recipient_mismatch`	400	The destination address does not match the required `payTo` address	Verify the transfer is sent to the correct Associated Token Account (ATA) for the `payTo` wallet
`invalid_asset_mismatch`	400	The token mint does not match the required asset	Use the correct SPL token mint address specified in `paymentRequirements.asset`

Transaction format errors

Code	HTTP	Description	Resolution
`invalid_transaction_format`	400	The transaction cannot be decoded	Ensure the transaction is a valid base64-encoded Solana transaction
`transaction_too_large`	400	The transaction exceeds the maximum allowed size	Reduce the transaction size by removing unnecessary instructions
`malformed_instruction`	400	An instruction in the transaction cannot be parsed	Verify all instructions use correct program IDs and data formats

Fee payer errors

Code	HTTP	Description	Resolution
`invalid_fee_payer`	400	The transaction fee payer is not the Kobaru facilitator	Set the facilitator's public key as the fee payer. The facilitator covers transaction fees

Compute budget errors

Code	HTTP	Description	Resolution
`missing_compute_budget_limit`	400	Transaction is missing the `SetComputeUnitLimit` instruction	Add a `SetComputeUnitLimit` instruction as the first instruction
`missing_compute_budget_price`	400	Transaction is missing the `SetComputeUnitPrice` instruction	Add a `SetComputeUnitPrice` instruction as the second instruction
`invalid_compute_unit_limit`	400	The compute unit limit is invalid or exceeds allowed maximum	Set a reasonable compute unit limit (typically 200,000-400,000 for token transfers)
`priority_fee_exceeds_limit`	400	The priority fee exceeds the maximum allowed by the facilitator	Reduce 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:

Code	HTTP	Description	Resolution
`invalid_instruction_count_topology`	400	The transaction has an unexpected number of instructions	Transactions must have exactly 4 instructions (or 5 if creating an ATA)
`invalid_instruction_topology_expected_create_ata`	400	Expected a CreateAssociatedTokenAccount instruction but found something else	If the recipient ATA doesn't exist, include a CreateATA instruction in position 3
`invalid_instruction_topology_ata_mismatch`	400	The ATA being created doesn't match the expected recipient	Ensure the CreateATA instruction creates an ATA for the correct recipient and mint
`missing_transfer_instruction`	400	No SPL token transfer instruction found	Include a `TransferChecked` instruction as the final instruction

Required instruction order:

SetComputeUnitLimit (ComputeBudget program)

SetComputeUnitPrice (ComputeBudget program)

CreateAssociatedTokenAccount (optional, if recipient ATA doesn't exist)

TransferChecked (SPL Token program)

Security errors

These errors prevent unauthorized use of the facilitator's resources:

Code	HTTP	Description	Resolution
`facilitator_cannot_pay_ata_creation`	400	The transaction attempts to have the facilitator pay for ATA creation rent	The payer (not the facilitator) must pay for ATA creation
`facilitator_cannot_be_payer`	400	The transaction source is the facilitator's wallet	You cannot transfer tokens from the facilitator's wallet
`facilitator_cannot_be_authority`	400	The facilitator is set as the transfer authority	The payer must be the authority for the token transfer
`facilitator_ata_cannot_be_source`	400	The source ATA belongs to the facilitator	You cannot transfer tokens from the facilitator's token account

Payer validation errors

Code	HTTP	Description	Resolution
`cannot_determine_payer`	400	Unable to determine the transaction payer from the transfer instruction	Ensure the transfer instruction has a valid source account
`invalid_payer_address_format`	400	The payer address is not a valid Solana public key	Use a valid base58-encoded Solana public key

Memo validation errors

Code	HTTP	Description	Resolution
`missing_required_memo`	400	Transaction is missing a required Memo instruction	Add a Memo instruction for payment attribution
`empty_memo`	400	The Memo instruction contains no data	Include meaningful memo content for payment tracking
`memo_too_long`	400	The memo exceeds the maximum allowed length	Reduce memo length (maximum varies by configuration)
`invalid_memo_format`	400	The memo format is invalid	Ensure the memo follows the required format for payment attribution

Transaction lifecycle errors

Code	HTTP	Description	Resolution
`blockhash_expired`	400	The transaction's recent blockhash has expired	Generate a new transaction with a fresh blockhash (blockhashes expire after ~60-90 seconds)
`transaction_signature_already_used`	409	This transaction signature has already been processed	This transaction was already submitted. Check the previous result
`simulation_failed`	400	Transaction simulation failed before submission	Check that the payer has sufficient SOL for fees and sufficient tokens for the transfer
`submission_failed`	500	Transaction submission or confirmation failed	The transaction may have been submitted but not confirmed. Check on-chain status before retrying

Settlement errors

Code	HTTP	Description	Resolution
`settle_timeout`	500	Settlement confirmation timed out	Check the transaction status on-chain. The transaction may still confirm
`settle_confirmation_failed`	500	Settlement transaction was submitted but confirmation failed	Verify the transaction status on a Solana explorer before retrying

Troubleshooting common errors

simulation_failed

Symptoms: Transaction verification returns simulation_failed before the transaction is submitted.

Common causes:

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)

Insufficient token balance - The source account doesn't have enough tokens

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:

Capability not configured - The network/scheme/asset combination hasn't been enabled for your account

Wrong network identifier - Using mainnet ID when your account is configured for devnet (or vice versa)

Wrong asset address - Using an incorrect token mint address

Resolution:

Navigate to Settings > Capabilities

Verify the correct network, scheme, and asset are enabled

For Solana devnet testing, use: solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1

For Solana mainnet, use: solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp

invalid_fee_payer

Symptoms: Transaction is rejected because the fee payer is incorrect.

Common causes:

Wrong fee payer set - The transaction specifies a fee payer other than the Kobaru facilitator

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 /v1/supported response.

blockhash_expired

Symptoms: Transaction is rejected because the blockhash has expired.

Common causes:

Stale transaction - The transaction was created too long ago (blockhashes expire after ~60-90 seconds)

Slow client - Network latency caused delays between transaction creation and submission

Resolution:

Create transactions with fresh blockhashes immediately before submission

Use getLatestBlockhash() with the finalized commitment for the most reliable blockhashes

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:

Retry collision - A previous request with the same signature is still being processed

Reused transaction - The same signed transaction was submitted multiple times

Resolution:

Wait for the original request to complete before retrying

If retrying, the API will return the cached result for the same idempotency key

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:

Priority fee too high - The compute unit price results in total fees exceeding the facilitator's limit

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

Security: facilitator_cannot_pay_ata_creation, facilitator_cannot_be_payer, facilitator_cannot_be_authority, facilitator_ata_cannot_be_source

Concurrency: duplicate_request, concurrent_capture_in_progress, transaction_signature_already_used

Server: unexpected_verify_error, unexpected_settle_error, server_configuration_error, settle_timeout, settle_confirmation_failed

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:

The full error response (including invalidReason)

Your request payload (redact sensitive information)

The timestamp of the request

Your client ID (available in the Console)

Error Handling

Error codes#

Error response format#

HTTP status codes#

General error codes#

Request validation errors#

Capability errors#

Concurrency errors#

Server errors#

Solana-specific error codes#

Amount and recipient errors#

Transaction format errors#

Fee payer errors#

Compute budget errors#

Instruction topology errors#

Security errors#

Payer validation errors#

Memo validation errors#

Transaction lifecycle errors#

Settlement errors#

Troubleshooting common errors#

simulation_failed#

capability_not_enabled#

invalid_fee_payer#

blockhash_expired#

duplicate_request#

priority_fee_exceeds_limit#

Error code quick reference#

By category#

Getting help#

Error codes

Error response format

HTTP status codes

General error codes

Request validation errors

Capability errors

Concurrency errors

Server errors

Solana-specific error codes

Amount and recipient errors

Transaction format errors

Fee payer errors

Compute budget errors

Instruction topology errors

Security errors

Payer validation errors

Memo validation errors

Transaction lifecycle errors

Settlement errors

Troubleshooting common errors

simulation_failed

capability_not_enabled

invalid_fee_payer

blockhash_expired

duplicate_request

priority_fee_exceeds_limit

Error code quick reference

By category

Getting help