Errors
When a request to the Startbutton API fails, the response provides clear details on what went wrong and how to resolve it. Each error follows a consistent structure, including a human-readable message, a machine-readable error code, and optional diagnostic information to support quick debugging.
As a RESTful API, Startbutton uses standard HTTP response codes to indicate whether a request was successful or failed.
HTTP Codes
400
Bad request (invalid input, business rule failure)
401
Unauthorized (invalid/expired auth, invalid secret/integration key, merchant not found)
403
Forbidden (IP not allowed, role/team, KYC restrictions)
404
Not found (resource/merchant/invoice/transaction not found)
409
Conflict (e.g. duplicate recipient, “Invoice Recipient already exists”)
422
Validation error (e.g. invalid lastUpdatedBy in query-transactions)
429
Rate limit exceeded
500
Internal server / generic error
FX rates
RATE_NOT_AVAILABLE
Rate not available
RATE_ZERO
Rate is zero
CURRENCY_PAIR_NOT_FOUND
Currency pair not found
Transfers
INSUFFICIENT_BALANCE
Transfer/refund failed due to low available balance
FAILED_TO_CREATE_RECIPIENT
Recipient creation failed (transfer/refund)
INVALID_BANK_CODE
Invalid bank code (defined in enum; rarely set in flows)
UNEXPECTED_ERROR
Generic unexpected error
DUPLICATE_PROVIDER_REFERENCE
Duplicate reference from provider
NO_AVAILABLE_PAYMENT_PARTNERS
No payout partner available for the transfer
Last updated