Error Reference

Every Wyrr API error includes a machine-readable code field and a human-readable message. Use the code to handle errors programmatically.

Error Response Format

{
  "error": {
    "code": "card_declined",
    "message": "The card was declined by the issuing bank.",
    "param": "payment_method",
    "doc_url": "https://docs.wyrr.com/errors#card_declined"
  }
}

Authentication

Errors related to API authentication and authorization.

Status	Code	Meaning	When It Occurs	How to Handle
401	`auth_invalid_key`	The API key provided is invalid or has been revoked.	Making any request with a malformed or revoked API key.	Verify your API key in the Dashboard under Settings > API Keys. Generate a new key if needed.
401	`auth_expired_token`	The access token has expired.	Using a token past its 15-minute lifetime.	Call /v1/auth/token/refresh with your refresh token, or re-authenticate.
403	`auth_insufficient_scope`	Your token does not have the required scope for this operation.	Attempting an action outside your token's scope (e.g., writing with a read-only key).	Request a token with the correct scopes, or upgrade your API key permissions.
403	`auth_ip_restricted`	Request originated from an IP address not in your allowlist.	Calling the API from a server IP not configured in your IP restriction settings.	Add the server IP to your allowlist in Dashboard > Settings > Security.

Validation

Errors when request parameters fail validation.

Status	Code	Meaning	When It Occurs	How to Handle
400	`invalid_request`	The request body is malformed or missing required fields.	Sending invalid JSON or omitting required parameters.	Check the request body against the API reference. Ensure all required fields are present.
400	`invalid_currency`	The currency code is not supported.	Passing a non-ISO-4217 code or an unsupported currency.	Use a supported ISO 4217 currency code. See /v1/fx/rates for supported pairs.
400	`invalid_amount`	The amount is out of the allowed range.	Passing a negative amount, zero, or exceeding the maximum transaction limit.	Ensure the amount is positive and within your account limits.
422	`unprocessable_entity`	The request is well-formed but semantically invalid.	Attempting an operation that conflicts with the current state (e.g., capturing an already-captured payment).	Check the resource's current status before retrying the operation.

Payment Processing

Errors during payment collection and payout processing.

Status	Code	Meaning	When It Occurs	How to Handle
402	`card_declined`	The card was declined by the issuing bank.	The issuer rejects the charge for various reasons (insufficient funds, fraud suspicion, etc.).	Ask the customer to try a different card or contact their bank.
402	`insufficient_funds`	The payment source does not have enough funds.	Customer's card or bank account balance is too low.	Prompt the customer to use an alternative payment method.
402	`payout_insufficient_balance`	Your Wyrr account balance is insufficient for this payout.	Attempting a payout that exceeds your available balance in the payout currency.	Wait for pending payments to settle or top up your balance.
402	`payment_method_unsupported`	The payment method is not available for this currency or region.	Using a payment rail not supported in the customer's country.	Check supported payment methods for the target currency and country.
409	`idempotency_conflict`	A request with this idempotency key was already processed with different parameters.	Reusing an idempotency key with a different request body.	Use a new idempotency key for distinct requests.
402	`fraud_suspected`	The transaction was blocked by Wyrr's fraud detection system.	Risk score exceeds threshold or sanctions screening match.	Review the transaction in Dashboard > Compliance. Contact support if you believe it's a false positive.

Rate Limiting

Errors when you exceed API rate limits.

Status	Code	Meaning	When It Occurs	How to Handle
429	`rate_limit_exceeded`	Too many requests in a short period.	Exceeding 1,000 requests per minute (live) or 100 per minute (test).	Implement exponential backoff. Check the Retry-After header for when to retry.
429	`concurrent_limit_exceeded`	Too many concurrent requests.	More than 25 simultaneous in-flight requests from the same API key.	Queue requests and limit concurrency. Use webhooks instead of polling.

Resource Errors

Errors when accessing or modifying resources.

Status	Code	Meaning	When It Occurs	How to Handle
404	`resource_not_found`	The requested resource does not exist.	Using an incorrect ID or accessing a deleted resource.	Verify the resource ID. Check if the resource was archived or deleted.
409	`resource_conflict`	The resource is in a conflicting state for this operation.	Attempting to modify a resource that is locked or in a terminal state.	Check the resource's current status before retrying.

Server Errors

Internal server errors and service availability issues.

Status	Code	Meaning	When It Occurs	How to Handle
500	`internal_error`	An unexpected error occurred on Wyrr's servers.	A bug or transient infrastructure issue.	Retry with exponential backoff. If persistent, check status.wyrr.com or contact support.
502	`bad_gateway`	A downstream service is unavailable.	A payment partner or banking rail is temporarily unreachable.	Retry after a short delay. The issue is usually transient.
503	`service_unavailable`	The API is temporarily unavailable.	During planned maintenance or unexpected outage.	Check status.wyrr.com for updates. Retry with exponential backoff.