Skip to main content
Complete reference of PIK API error codes, what they mean, and how to handle them in your integration.
When a PIK API request fails, the response body includes an error object with a code, a message, and in some cases additional detail fields to help you diagnose the issue. Use the error code rather than the HTTP status code or message text to handle errors programmatically — codes are stable across API versions, messages may change.

​
Error response format

Every error response from the PIK API follows this structure: The response includes an error object containing: code (a machine-readable string identifying the error type), message (a human-readable description of what went wrong), and optionally detail (additional context such as which field failed validation or what the current account status is).

​
HTTP status codes

400 Bad Request — The request was malformed or missing required fields. Check the detail field for which parameter is invalid. 401 Unauthorized — Authentication failed. Your API key is missing, invalid, expired, or has been revoked. 403 Forbidden — Your request was authenticated but not permitted. This usually means the connected account does not have the required capability activated, or the account has not been verified. 404 Not Found — The resource you requested does not exist. Check that the ID in the URL is correct and belongs to your platform account. 409 Conflict — The request conflicts with the current state of the resource. For example, attempting to activate a capability that is already active. 422 Unprocessable Entity — The request was well-formed but could not be processed due to a business logic rule. See the specific error codes below. 429 Too Many Requests — You have exceeded the API rate limit. Back off and retry after the time indicated in the Retry-After header. 500 Internal Server Error — An unexpected error occurred on PIK’s side. Retry with exponential backoff. If the issue persists, contact PIK support.

​
Specific error codes

INVALID_API_KEY — The API key provided is not recognised. Verify the key is correct and has not been deleted. API_KEY_REVOKED — The API key has been revoked. Generate a new key from the PIK Dashboard. ACCOUNT_NOT_VERIFIED — The connected account’s verification status is not approved. Complete KYC/KYB verification before activating capabilities or transacting. ACCOUNT_NOT_FOUND — No connected account with the provided ID exists under your platform. CAPABILITY_NOT_ACTIVATED — The requested action requires a capability that has not been activated on this account. Activate the capability first. CAPABILITY_ALREADY_ACTIVE — You attempted to activate a capability that is already active on the account. INSUFFICIENT_BALANCE — The wallet does not have enough available balance to complete the transaction. Check the balance and top up if needed. BELOW_MINIMUM_AMOUNT — The requested amount is below the minimum allowed for this transaction type or currency pair. ABOVE_MAXIMUM_AMOUNT — The requested amount exceeds the maximum allowed for this transaction type. UNSUPPORTED_CURRENCY — The currency specified is not supported by PIK or is not available for the requested operation. UNSUPPORTED_CURRENCY_PAIR — The sell/buy currency combination is not a supported FX pair. QUOTE_EXPIRED — The quote_id provided has passed its validity window. Request a new quote and resubmit. QUOTE_ALREADY_USED — The quote_id has already been used for a conversion. Each quote can only be used once. PAYMENT_ALREADY_SETTLED — You attempted an action on a payment that has already been settled. PAYMENT_EXPIRED — You attempted an action on a payment that has expired. DUPLICATE_REFERENCE — A payment or transfer with the same reference already exists. Use a unique reference for each transaction. RATE_LIMIT_EXCEEDED — You have made too many requests in a short period. Implement exponential backoff and retry after the Retry-After interval. WEBHOOK_URL_UNREACHABLE — PIK could not reach the webhook URL you provided during registration. Ensure the URL is publicly accessible over HTTPS.