Error Code Reference

A comprehensive list of all the errors that can be thrown by the Cash App Pay API

Overview

This reference describes every error that can occur within the Cash App Pay APIs, why it happened, and how to resolve it.

Error Schema

Errors in the Cash App Pay API are returned in every endpoint with the same format: an array of error objects at the top level of the response. Here’s an example:

Example Error

{
  "errors": [
    {
      "category": "INVALID_REQUEST_ERROR",
      "code": "MISSING_REQUIRED_FIELD",
      "detail": "Missing required parameter 'amount'",
      "field": "amount"
    }
  ]
}

Each error has the following fields:

Field Name	Description
category string, required	Contains a high-level grouping of the error that occurred from the following values: - API_ERROR - AUTHENTICATION_ERROR - BRAND_ERROR - DISPUTE_ERROR - GRANT_ERROR - MERCHANT_ERROR - INVALID_REQUEST_ERROR - PAYMENT_PROCESSING_ERROR - RATE_LIMIT_ERROR
code string, required	Contains a stable error code from the list of codes on this page. This field is versioned, and can safely be used for error handling.
detail string, optional	Describes the error in human-readable US English, with description of why it occurred and how to resolve it. This field is not structured or versioned, and may change at any time. Do not rely on the detail field for error handling; instead, rely on the code field.
field string, optional	Contains the name of the field that caused and / or is related to this error, in JSON dot notation format.

Retry Behaviors

All requests to the Cash App Pay API are idempotent, but you should only retry requests in certain cases. There are 3 types of retry behaviors documented below:

Retry Type	Description
Retryable	The error can be resolved by retrying the request as-is, possibly after waiting a short period of time. No changes to the request are necessary to retry and possibly get a different response. This retry behavior is typically associated with rate limiting, internal server errors, or waiting for automated state transitions.
Retryable with New Payload	The error can be resolved by retrying the request, but requires changing the request payload first. This retry behavior is typically associated with validation failures, where the API client isn’t sending valid data.
Permanent (Do Not Retry)	The error cannot be resolved by retrying the request in any capacity. This behavior is typically associated with payment or refund declines, where the API client sent a valid request, but Cash App Pay rejected it. The API client will need to create a new request and grant to proceed instead of attempting to modify/reuse an existing one.

For more information about handling errors in your code, see error handling.

Authentication Errors

The following errors occur before a request is processed by the Cash App API, during authentication and authorization. They are typically related to issues with the credentials passed to the API.

All validation errors have a category of AUTHENTICATION_ERROR.

Error Code	Description and Resolution
UNAUTHORIZED HTTP 401 Retryable with New Payload	The Cash App Pay API could not authenticate your request. This is typically due to: - Using sandbox credentials in production (or vice versa) - Using an invalid syntax for the authorization header - Using a mismatched client ID / API key pair To resolve this issue, double-check that you’ve set your credentials in the authorization header properly for the endpoint you’re calling. If you can’t resolve it with your existing credentials, reach out to Cash App Pay support and we’ll issue new credentials for you or look into why your requests aren’t being authenticated properly.
ACCESS_TOKEN_REVOKED HTTP 401 Retryable with New Payload	The client ID and API key provided were both valid and in the correct format, but the API key was revoked and may no longer be used to make calls. Refresh your API credentials to get a new API key and resolve this issue.
ACCESS_TOKEN_EXPIRED HTTP 401 Retryable with New Payload	The client ID and API key provided were both valid and in the correct format, but the API key has expired and may no longer be used to make calls. Refresh your API credentials to get a new API key and resolve this issue.
CLIENT_DISABLED HTTP 401 Retryable	The client ID and API key provided were both valid and in the correct format, but the API client has been disabled by Cash App Pay and is not allowed to make API calls. Reach out to Cash App Pay support if your API client has been improperly disabled, and they can get it re-enabled for you.
FORBIDDEN HTTP 403 Retryable with New Payload	The access token and client ID provided were valid, but don’t have access to the requested resource. Typically, this is caused by passing a resource ID that isn’t valid or managed by this API client.
INSUFFICIENT_SCOPES HTTP 403 Retryable with New Payload	The client ID and API key provided were both valid and in the correct format, and the client itself has access to the requested resource. However, this specific access token does not have the required permissions to perform the current action on the resource. Use a different API key that has permissions for the endpoint you’re calling to resolve this.

Validation Errors

The Cash App Pay API validates all requests sent by API clients to ensure they match the documented schemas. If a request does not match the schema, a validation error will be returned.

All validation errors have a category of INVALID_REQUEST_ERROR.

Do not automatically retry validation errors

Validation errors will continue to return the same error code if the API client continues to make requests with the same payload. Retrying the request will not change the response

General Validation Errors

The following errors may occur when the request is unable to be parsed due to invalid data being passed by the API client. These errors may occur on any request or field, regardless of the field’s data type.

Error Code	Description and Resolution
EXPECTED_JSON_BODY HTTP 400 Retryable with New Payload	The API client sent a request without a JSON payload to an endpoint that requires a payload, or the JSON provided in the payload was unparseable. The API client should make sure that it is passing a valid JSON payload to the endpoint. If you’re not sure if your JSON is valid, try using an online JSON validation tool (there are many of them) to give you feedback.
MISSING_REQUIRED_PARAMETER HTTP 400 Retryable	The API client did not provide a required query or body parameter. Refer to the `field` parameter on the error object to see which field should have been present, but was not found in the payload.
CONFLICTING_PARAMETERS HTTP 400 Retryable with New Payload	The API client sent a request payload that repeats parameters in the body that would overwrite each other (i.e., duplicate keys). Refer to the `field` parameter on the error object to see which field had duplicates in the request payload.
UNKNOWN_QUERY_PARAMETER HTTP 400 Retryable with New Payload	The API client sent a query parameter that does not exist in this version of the API. Refer to the `field` parameter on the error object to see which field could not be recognized. The Cash App Pay API returns errors for unknown fields to prevent API clients from setting a field that isn’t supported in a given API version, which could cause data integrity issues.
UNKNOWN_BODY_PARAMETER HTTP 400 Retryable with New Payload	The API client sent a field in the request payload that does not exist in this version of the API. Refer to the `field` parameter on the error object to see which field could not be recognized. The Cash App Pay API returns errors for unknown fields to prevent API clients from setting a field that isn’t supported in a given API version, which could cause data integrity issues.
INVALID_CONTENT_TYPE HTTP 400 Retryable with New Payload	The API client specified a Content-Type header on the request that is not supported by the endpoint. Two content types are used in the API: - application/json, the standard type for all endpoints except file uploads - multipart/form-data, for file uploads only; part of the request is a JSON payload, the other part is a binary representation of the file. The API client must set one of these content types as the header on each request. No other content types are accepted.
MISSING_REGION HTTP 400 Retryable with New Payload	The API client did not set the required X-Region header. The API uses regions to provide lower latencies for API clients, enforce idempotency, and respect data sovereignty. Regions (in the form of an IATA airport code) must be specified on each request using the X-Region header. See Regions and Localization for more information.
INVALID_REGION HTTP 400 Retryable with New Payload	The API client set the required X-Region header to an unrecognized code. The API client should change the X-Region header value to a valid code from the Regions and Localization page.
FEATURE_DISABLED HTTP 400 Retryable with New Payload	The API client set a field that requires a feature which is currently disabled for them. The API client should stop using the functionality described in the message of the error and reach out to Cash App Pay support to request access if necessary.

String Validation Errors

The following errors may occur when a request fails validation due to invalid data being passed to a field that accepts string values.

Error Code	Description and Resolution
EXPECTED_STRING HTTP 400 Retryable with New Payload	The API client passed a non-string value to a field that only accepts strings. Refer to the `field` parameter on the error object to see which field should have been a string, but received a different data type.
VALUE_TOO_LONG HTTP 400 Retryable with New Payload	The API client passed a string with too many characters to a field that has a maximum character length requirement. Refer to the `field` parameter on the error object to see which field had too many characters. The API documentation for that field should include the maximum character length it requires.
VALUE_TOO_SHORT HTTP 400 Retryable with New Payload	The API client passed a string with too few characters to a field that has a minimum character length requirement. Refer to the `field` parameter on the error object to see which field had too few characters. The API documentation for that field should include the minimum character length it requires.
VALUE_EMPTY HTTP 400 Retryable with New Payload	The API client passed an empty string or whitespace-only string to a field that requires a non-empty value. Refer to the `field` parameter on the error object to see which field failed validation. The API client must pass at least one non-whitespace character to pass this validation.
INVALID_TIME HTTP 400 Retryable with New Payload	The API client passed a value which could not be parsed by the server to a field accepting RFC-3339 formatted dates and / or timestamps, or the passed timestamp was not using UTC. Refer to the `field` parameter on the error object to see which field has an invalid date or timestamp. The API requires all time-related values to comply with RFC-3339, which is a more restrictive subset of the ISO-8601 standard: - Dates are formatted as YYYY-MM-DD. - Timestamps are formatted as YYYY-MM-DDTHH:MM:DDZ. Note that all timestamps must be in UTC time, or they will fail validation.
INVALID_EMAIL_ADDRESS HTTP 400 Retryable with New Payload	The API client passed a value which could not be parsed by the server to a field accepting well-formatted email addresses. Refer to the `field` parameter on the error object to see which field has an invalid email address. At a minimum, the API requires email addresses to contain at least one character followed by an @ sign and then at least one more character, i.e. a@b.
INVALID_PHONE_NUMBER HTTP 400 Retryable with New Payload	The API client passed a value which could not be parsed by the server to a `field` accepting well-formatted phone numbers. Refer to the `field` parameter on the error object to see which field has an invalid phone number. We recommend using libphonenumber to validate phone numbers before passing them to the API.
INVALID_URL HTTP 400 Retryable with New Payload	The API client passed a value which could not be parsed by the server to a field accepting well-formatted URL. Refer to the `field` parameter on the error object to see which field has an invalid URL. At a minimum, the API requires URLs to start with http:// or https:// and contain a domain and / or IP address.

Integer Validation Errors

The following errors may occur when a request fails validation due to invalid data being passed to a field that accepts integer values.

Error Code	Description and Resolution
EXPECTED_INTEGER HTTP 400 Retryable with New Payload	The API client passed a non-integer value to a field that only accepts integers. Refer to the `field` parameter on the error object to see which field should have been a integer, but received a different data type.
VALUE_TOO_HIGH HTTP 400 Retryable with New Payload	The API client passed a larger integer than allowed to an integer field. Refer to the `field` parameter on the error object to see which integer field requires a smaller value, then retry the request with a valid integer.
VALUE_TOO_LOW HTTP 400 Retryable with New Payload	The API client passed a smaller integer than allowed to an integer field. Refer to the `field` parameter on the error object to see which integer field requires a larger value, then retry the request with a valid integer.

Boolean Validation Errors

The following errors may occur when a request fails validation due to invalid data being passed to a field that accepts boolean values.

Error Code	Description and Resolution
EXPECTED_BOOLEAN HTTP 400 Retryable with New Payload	The API client passed a non-boolean value to a field that only accepts booleans. Refer to the `field` parameter on the error object to see which field should have been a boolean, but received a different data type.

Array Validation Errors

The following errors may occur when a request fails validation due to invalid data being passed to a field that accepts array values.

Error Code	Description and Resolution
EXPECTED_ARRAY HTTP 400 Retryable with New Payload	The API client passed a non-array value to a field that only accepts arrays. Refer to the `field` parameter on the error object to see which field should have been an array, but received a different data type.
ARRAY_LENGTH_TOO_LONG HTTP 400 Retryable with New Payload	The API client passed more than the minimum number of elements to an array field. Refer to the `field` parameter on the error object to see which array field requires fewer elements.
ARRAY_LENGTH_TOO_SHORT HTTP 400 Retryable with New Payload	The API client passed fewer than the minimum number of elements to an array field. Refer to the `field` parameter on the error object to see which array field requires additional elements.
INVALID_ARRAY_TYPE HTTP 400 Retryable with New Payload	The API client passed an array to an array field, which is valid, but the data type within the array did not match the expected data type. Refer to the `field` parameter on the error object to see which array field has an invalid data type, then use the detail field to see what the correct data type is.

Object Validation Errors

The following errors may occur when a request fails validation due to invalid data being passed to a field that accepts nested objects.

Error Code	Description and Resolution
EXPECTED_OBJECT HTTP 400 Retryable with New Payload	The API client passed a non-object value to a field that only accepts objects. Refer to the `field` parameter on the error object to see which field should have been an object, but received a different data type.

Map Validation Errors

The following errors may occur when a request fails validation due to invalid data being passed to a field that accepts maps.

Error Code	Description and Resolution
TOO_FEW_MAP_ENTRIES HTTP 400 Retryable with New Payload	The API client did not add enough keys to the map. Refer to the `field` parameter on the error object to see which field was not provided with enough keys.
TOO_MANY_MAP_ENTRIES HTTP 400 Retryable with New Payload	The API client added too many keys to the map. Refer to the `field` parameter on the error object to see which field has too many map keys.

Common Runtime Errors

The following error codes are re-used throughout the Cash App Pay API and handle common errors, such as missing resources, pagination problems, and idempotency key reuse.

All of the following errors have a category of INVALID_REQUEST_ERROR.

Error Code	Description and Resolution
NOT_FOUND HTTP 404 Retryable with New Payload	The API client requested a resource that could not be found or isn’t owned by the client. The API client should ensure that it is passing the correct ID in the request. Unless the ID parameter is changed, the endpoint will continue to respond with a “not found” error and the client should not retry the request.
CONFLICT HTTP 409 Retryable	The action to perform on the resource cannot be completed due to a conflict with the current state of the resource or its related resources.
INVALID_CURSOR HTTP 400 Retryable with New Payload	The API client provided a cursor to a paginated endpoint that could not be parsed by the API.The API client should ensure that it is passing the correct cursor in the request. If the API client can’t identify a valid cursor to provide, it should restart pagination by passing a blank cursor in the request and getting a new, valid cursor from the response. Unless the cursor parameter is changed, the endpoint will continue to respond with an “invalid cursor” error and the client should not retry the request.
IDEMPOTENCY_KEY_REUSED HTTP 400 Retryable with New Payload	The idempotency key provided by the API client has already been used with a different request payload on this endpoint. The API client must retry the request with a different idempotency key.
INVALID_STATE_TRANSITION HTTP 400 Retryable with New Payload	The API client is attempting a change not allowed by the state machine for the resource. This error indicates that the API client is referring to stale data or has a bug in its business logic. The API client should not retry the request.
CLIENT_NOT_FOUND HTTP 400 Retryable with New Payload	The API client passed a client ID value in the request payload that did not match the API client’s ID, OR no client could be found for the given client ID in the request payload. The API client must retry the request with a different (and valid) client ID.
IDEMPOTENCY_PAYLOAD_MISMATCH HTTP 400	A previous idempotency key was already used to perform an action on the given resource with the given payload. The action cannot be performed again with a new idempotency key.

Rate Limit Errors

The Cash App Pay API rate limits OLAP (online analytical processing) requests to guarantee that the Cash App Pay service stays fast and stable. These include operations such as:

Listing payments for an API client by reference ID
Retrieving a list of active grants approved by a given customer
…and any other “list” or “search” endpoints in the API

Reach out to Cash App Pay support at any time to request rate limit increases on these endpoints, and we will be happy to adjust them for you.

Payment processing requests are never rate-limited

OLTP (online transaction processing) requests related to payment acceptance are never rate-limited. This includes, but is not limited to:

Creating, reading, voiding, and capturing individual Payments
Creating, reading, voiding, and capturing individual Refunds
Creating, upserting, reading, and updating individual Bbrands
Creating, upserting, reading, and updating individual Merchants
Creating, reading, and updating Customer Requests
Reading and revoking Individual Grants

Refer to the API reference pages for any endpoint to see if it’s rate limited.

Error Code	Description and Resolution
RATE_LIMITED HTTP 429 Retryable	The API client is making too many requests too quickly and should reduce the number of calls it’s making to the API. Rate-limited requests are not checked for validity, so errors may be encountered when they are retried later on. The API client should retry the requests at a slower pace using exponential backoff.

Payment Processing Errors

The following error codes may occur in payment processing flows. In addition to these errors, grant errors may occur during payment processing, while using grants to create a payment.

All payment processing errors have a category of PAYMENT_PROCESSING_ERROR.

Error Code	Description and Resolution
MERCHANT_NOT_FOUND HTTP 400 Retryable with New Payload	The API client provided a merchant ID in the request that could not be found or isn’t owned by the client. The API client should ensure that it is passing the correct merchant ID in the request. Unless the merchant ID parameter is changed, the endpoint will continue to respond with a “not found” error and the client should not retry the request.
PAYMENT_NOT_FOUND HTTP 400 Retryable with New Payload	The API client provided a payment ID or idempotency key in the request that could not be found or isn’t owned by the client. The API client should ensure that it is passing the correct payment ID or idempotency key in the request. Unless the payment ID or idempotency key parameter is changed, the endpoint will continue to respond with a “not found” error and the client should not retry the request.
REFUND_NOT_FOUND HTTP 400 Retryable with New Payload	The API client provided a refund ID or idempotency key in the request that could not be found or isn’t owned by the client. The API client should ensure that it is passing the correct refund ID or idempotency key in the request. Unless the refund ID or idempotency key parameter is changed, the endpoint will continue to respond with a “not found” error and the client should not retry the request.
CUSTOMER_DISABLED HTTP 400 Permanent (Do Not Retry)	The customer the API client is trying to take a payment or issue a refund for is deactivated in Cash App Pay and cannot send or receive funds. The payment or refund is declined. The API client should consider this a permanent decline. Retrying the request will not change the response. Grants are consumed by this decline.
MERCHANT_DISABLED HTTP 400 Retryable	The merchant the API client is trying to take a payment or issue a refund for is deactivated in Cash App Pay and cannot send or receive funds. The payment or refund is declined. The API client should consider this a retryable decline. Retrying the request when a merchant has become active will change the response. Grants are not consumed by this decline. Merchants can be deactivated by Cash App or by the API client. API client-initiated deactivations can be reversed using the UpdateMerchant endpoint. Cash App-initiated deactivations are permanent and cannot be reversed.
MERCHANT_PENDING HTTP 400 Retryable	The merchant the API client is trying to take a payment or issue a refund for is still being onboarded to Cash App Pay. The API client should consider this a retryable decline. Retrying the request once the merchant is active will change the response. Grants are not consumed by this decline. The API client must wait for the merchant to move from a status of PENDING to ACTIVE before using it to take payments or issue refunds. This generally happens within 15 minutes of merchant creation, but may take longer in rare cases.
PAYMENT_DECLINED_COMPLIANCE HTTP 400 Permanent (Do Not Retry)	Cash App Pay detected a violation of terms of service, Program Rules, or applicable laws for the payment the API client is trying to create or capture. The payment is declined. The API client should consider this a permanent decline. Retrying the request will not change the response. Grants are consumed by this decline. No detail will be given as to what caused the compliance decline in the API; reach out to Cash App Pay support if you need to know more about an individual decline.
PAYMENT_DECLINED_INSUFFICIENT_FUNDS HTTP 400 Permanent (Do Not Retry)	The customer the API client is attempting to take a payment from does not have sufficient funds to complete the payment. The API client should consider this a permanent decline. Retrying the request will not change the response. Grants are consumed by this decline.
PAYMENT_DECLINED_LIMIT_REACHED HTTP 400 Permanent (Do Not Retry)	The customer the API client is attempting to take a payment from has reached the maximum amount of money they’re allowed to spend from their account in a given time period. The API client should consider this a permanent decline. Retrying the request will not change the response. Grants are consumed by this decline.
PAYMENT_DECLINED_OTHER HTTP 400 Permanent (Do Not Retry)	The API declined the payment for an unknown reason. Used as a fallback when a more specific reason is not applicable. The API client should consider this a permanent decline. Retrying the request will not change the response. Grants are consumed by this decline.
PAYMENT_DECLINED_RISK HTTP 400 Permanent (Do Not Retry)	Cash App Pay detected this payment as having a high likelihood of fraud. The payment is declined. The API client should consider this a permanent decline. Retrying the request will not change the response. Grants are consumed by this decline. No detail will be given as to what caused the risk decline in the API; reach out to Cash App Pay support if you need to know more about an individual decline.
PAYMENT_DECLINED_CUSTOMER_BLOCKED_MERCHANT HTTP 400 Permanent (Do Not Retry)	The customer the API client is attempting to take a payment from has blocked the merchant from sending them payments. The payment is declined. The API client should consider this a permanent decline. Retrying the request will not change the response. Reach out to Cash App Pay support if you need to know more about an individual decline.
PAYMENT_INVALID_AMOUNT_MISMATCH HTTP 400 Retryable with New Payload	The amount the API client intended to created the payment with did not match the amount shown to the customer during the customer request for payment. The API client should consider this a retryable decline. Retrying the request with an amount that matches the one shown on the customer request will change the response. Grants are not consumed by this decline.
PAYMENT_INVALID_CURRENCY_MISMATCH HTTP 400 Retryable with New Payload	The currency the API client intended to created the payment with did not match the currency shown to the customer during the customer request for payment, or the currency of the merchant did not match the payment’s currency. The API client should consider this a retryable decline. Retrying the request with a currency that matches the one shown on the customer request and the one on the merchant will change the response. Grants are not consumed by this decline.
PAYMENT_INVALID_TOO_LARGE HTTP 400 Retryable with New Payload	The API declined the payment due to the amount being too high. The maximum payment size may be adjusted to prevent fraud, though this is not equivalent to a risk decline. The API client should consider this a retryable decline. Retrying the request with a lower amount may change the response. Grants are not consumed by this decline.
PAYMENT_INVALID_TOO_SMALL HTTP 400 Retryable with New Payload	The API declined the payment due to the amount being too low (below $0.01 USD). The API client should consider this a retryable decline. Retrying the request with a larger amount may change the response. Grants are not consumed by this decline.
REFUND_DECLINED_COMPLIANCE HTTP 400 Permanent (Do Not Retry)	Cash App Pay detected a violation of terms of service, Program Rules, or applicable laws for the refund the API client is trying to create or capture. The refund is declined. The API client should consider this a permanent decline. Retrying the request will not change the response. Grants are consumed by this decline. No detail will be given as to what caused the compliance decline in the API; reach out to Cash App Pay support if you need to know more about an individual decline.
REFUND_DECLINED_OTHER HTTP 400 Permanent (Do Not Retry)	The API declined the refund for an unknown reason. Used as a fallback when a more specific reason is not applicable. The API client should consider this a permanent decline. Retrying the request will not change the response. Grants are consumed by this decline.
REFUND_DECLINED_RISK HTTP 400 Permanent (Do Not Retry)	Cash App Pay detected this refund as having a high likelihood of fraud. The payment is declined. The API client should consider this a permanent decline. Retrying the request will not change the response. Grants are consumed by this decline. No detail will be given as to what caused the risk decline in the API; reach out to Cash App Pay support if you need to know more about an individual decline.
REFUND_INVALID_CURRENCY_MISMATCH HTTP 400 Retryable with New Payload	The currency the API client intended to create the refund with is invalid for one or more of the following reasons: - The currency of the merchant does not match the currency of the refund - The currency of the payment being refunded does not match the currency of the refund The API client should consider this a retryable decline. Retrying the request with a correctly-matched currency changes the response.
REFUND_INVALID_PAYMENT_UNCAPTURED HTTP 400 Retryable with New Payload	The API declined the refund because the linked payment has not been captured. The API client should void the original payment instead of issuing a refund.
REFUND_INVALID_TOO_LARGE HTTP 400 Retryable with New Payload	The API declined the payment due to the amount being too high. This could be due to a disputed payment which the merchant lost. The maximum payment size can be adjusted to prevent fraud, though this is not equivalent to a risk decline. The API client should consider this a retryable decline. Retrying the request with a lower amount may change the response. Grants are not consumed by this decline.
REFUND_INVALID_TOO_SMALL HTTP 400 Retryable with New Payload	The API declined the refund due to the amount being too low (below $0.01 USD). The API client should consider this a retryable decline. Retrying the request with a larger amount may change the response. Grants are not consumed by this decline.
REFUND_INVALID_SCOPE_MISMATCH HTTP 400	A payment/refund cannot be processed for this client because it has missing bank account configurations necessary for settlement purposes.
MISSING_SETTLEMENT_CONFIGURATION HTTP 400	A payment/refund cannot be processed for this client because it has missing configurations necessary for reporting purposes.

Payouts

The following error codes may occur while creating payouts. All payout errors have a category of PAYOUT_PROCESSING_ERROR.

In addition to the payout-specific error codes below, payouts may also return shared merchant and customer errors listed above, such as MERCHANT_NOT_FOUND, MERCHANT_DISABLED, MERCHANT_PENDING, and CUSTOMER_DISABLED.

Error Code	Description and Resolution
PAYOUT_DECLINED_INSUFFICIENT_FUNDS HTTP 400 Retryable	The merchant does not have sufficient funds or collateral for the payout. The API client should consider this a retryable decline. Retrying the payout after the merchant’s balance or collateral situation is resolved may change the response. If this error is returned by Create payout, the payout is still created with a `DECLINED` status. One-time grants are consumed by `PAYOUT_DECLINED_*` errors, so the API client must repeat the Customer Request flow to obtain a new grant before retrying.
PAYOUT_INVALID_CURRENCY HTTP 400 Retryable with New Payload	The payout was created with an unsupported currency. The API client should retry the request with a supported currency. `PAYOUT_DECLINED_*` errors consume one-time grants; other payout errors do not.
PAYOUT_DECLINED_RISK HTTP 400 Permanent (Do Not Retry)	Cash App Pay declined the payout due to fraud or other risky activity. The API client should consider this a permanent decline. Retrying the request will not change the response. If this error is returned by Create payout, the payout is still created with a `DECLINED` status and the one-time grant is consumed. No detail will be given as to what caused the risk decline in the API; reach out to Cash App Pay support if you need to know more about an individual decline.
PAYOUT_DECLINED_OTHER HTTP 400 Permanent (Do Not Retry)	The payout was declined for an unknown reason. Used as a fallback when a more specific reason is not applicable. The API client should consider this a permanent decline. Retrying the request will not change the response. If this error is returned by Create payout, the payout is still created with a `DECLINED` status and the one-time grant is consumed.
PAYOUT_DECLINED_LIMIT_REACHED HTTP 400 Permanent (Do Not Retry)	The payout was declined because the customer or merchant has reached a payout limit for the current time period. The API client should consider this a permanent decline. Retrying the request will not change the response. If this error is returned by Create payout, the payout is still created with a `DECLINED` status and the one-time grant is consumed.

Merchant & Brand Registration Errors

The following error codes may occur while managing merchants and brands on Cash App Pay.

All merchant registration errors have a category of MERCHANT_ERROR or BRAND_ERROR.

Error Code	Description and Resolution
BRAND_NOT_FOUND HTTP 400 Retryable with New Payload	The API client provided a brand ID in the request that could not be found or isn’t owned by the client. The API client should ensure that it is passing the correct brand ID in the request. Unless the brand ID parameter is changed, the endpoint will continue to respond with a “not found” error and the client should not retry the request.
MERCHANT_MISSING_ADDRESS_OR_SITE HTTP 400 Retryable with New Payload	The API client tried to create or update a merchant and set both the address and site URL fields to null. Merchants require an address or site URL. The API client should set an address or site URL in the payload to resolve this error, then retry the request.

Grant Errors

The following error codes may occur while using any endpoint that interacts with grants, including ones used to create payments or refunds.

All grant errors have a category of GRANT_ERROR.

Error Code	Description and Resolution
GRANT_ACTION_TYPE_MISMATCH HTTP 400 Retryable with New Payload	The API found the provided grant and attempted to use it, but failed due to the grant’s action not being compatible with the endpoint being called. The grant was not consumed. The API client should send the customer through the customer request flow with the correct action type for the endpoint it wants to call and generate a valid grant.
GRANT_CONSUMED HTTP 400 Retryable with New Payload	The API found the provided grant and attempted to use it, but failed due to the grant being previously used (for one-time grants). The API client should send the customer through the customer request flow again to generate a fresh, unused, grant.
GRANT_EXPIRED HTTP 400 Retryable with New Payload	The API found the provided grant and attempted to use it, but failed due to the grant having expired. The API client should send the customer through the customer request flow again to generate a fresh grant.
GRANT_NOT_FOUND HTTP 400 Retryable with New Payload	The API client provided a grant ID in the request that could not be found or isn’t owned by the client. The API client should ensure that it is passing the correct grant ID in the request. Unless the grant ID parameter is changed, the endpoint will continue to respond with a “not found” error and the client should not retry the request.
GRANT_REVOKED HTTP 400 Retryable with New Payload	The API found the provided grant and attempted to use it, but failed due to the grant having been revoked. The API client should send the customer through the customer request flow again to generate a fresh grant.

Dispute Errors

The following error codes may occur while using any endpoint that responds to disputes.

All dispute errors have a category of DISPUTE_ERROR.

Error Code	Description and Resolution
DISPUTE_MISSING_EVIDENCE HTTP 400 Retryable	The request to challenge the dispute was valid and a dispute existed for the provided ID, but no evidence was found to challenge the dispute with. Since no evidence results in an automatic loss of the dispute, API clients are not allowed to “challenge” a dispute without evidence. If you want to respond to a dispute with no evidence, you should instead call the AcceptDispute endpoint, which makes the intent to “lose” the dispute explicit. Otherwise, upload evidence for the dispute and then re-attempt challenging it.

Error Code

Description and Resolution

DISPUTE_MISSING_EVIDENCE
HTTP 400
Retryable

The request to challenge the dispute was valid and a dispute existed for the provided ID, but no evidence was found to challenge the dispute with. Since no evidence results in an automatic loss of the dispute, API clients are not allowed to “challenge” a dispute without evidence.

If you want to respond to a dispute with no evidence, you should instead call the AcceptDispute endpoint, which makes the intent to “lose” the dispute explicit. Otherwise, upload evidence for the dispute and then re-attempt challenging it.

Webhook Errors

The following error codes may occur while using any webhook related endpoints.

All webhook errors have a category of WEBHOOK_ERROR.

Error Code	Description and Resolution
WEBHOOK_ENDPOINT_NOT_FOUND HTTP 400 Retryable with New Payload	The API client provided a webhook endpoint ID in the request that could not be found or isn’t owned by the client. The API client should ensure that it is passing the correct webhook endpoint ID in the request. Unless the webhook endpoint ID parameter is changed, the endpoint will continue to respond with a “not found” error and the client should not retry the request.
WEBHOOK_ENDPOINT_TOO_MANY HTTP 400	The maximum number of webhook endpoints for the client has been reached. Delete existing webhook endpoints before trying to create new ones.

Customer Errors

The following error codes may occur while using any customer-related endpoints.

All customer errors have a category of CUSTOMER_ERROR.

Error Code	Description and Resolution
CUSTOMER_DELETED_ACCOUNT HTTP 400 Permanent (Do Not Retry)	The customer account has been deleted. This is a permanent operation that cannot be revoked.

API Errors

In the rare event that the Cash App Pay APIs experience issues, the error codes below will be returned.

All server errors (ones not caused by the API client) have a category of API_ERROR.

Error Code	Description and Resolution
INTERNAL_SERVER_ERROR HTTP 500 Retryable	A general server error occurred, due to an issue with the API. The API client should retry its request. If errors continue, reach out to Cash App Pay support.
SERVICE_UNAVAILABLE HTTP 503 Retryable	The API being called is experiencing an outage. The API client should retry its request. If errors continue, reach out to Cash App Pay support.
GATEWAY_TIMEOUT HTTP 504 Retryable	The API was unable to process the request in a reasonable period of time and terminated the request. The API client should retry its request. If errors continue, reach out to Cash App Pay support.

A comprehensive list of all the errors that can be thrown by the Cash App Pay API

Overview

This reference describes every error that can occur within the Cash App Pay APIs, why it happened, and how to resolve it.

Error Schema

Errors in the Cash App Pay API are returned in every endpoint with the same format: an array of error objects at the top level of the response. Here’s an example:

Example Error

{
  "errors": [
    {
      "category": "INVALID_REQUEST_ERROR",
      "code": "MISSING_REQUIRED_FIELD",
      "detail": "Missing required parameter 'amount'",
      "field": "amount"
    }
  ]
}

Each error has the following fields:

Field Name	Description
category string, required	Contains a high-level grouping of the error that occurred from the following values: - API_ERROR - AUTHENTICATION_ERROR - BRAND_ERROR - DISPUTE_ERROR - GRANT_ERROR - MERCHANT_ERROR - INVALID_REQUEST_ERROR - PAYMENT_PROCESSING_ERROR - RATE_LIMIT_ERROR
code string, required	Contains a stable error code from the list of codes on this page. This field is versioned, and can safely be used for error handling.
detail string, optional	Describes the error in human-readable US English, with description of why it occurred and how to resolve it. This field is not structured or versioned, and may change at any time. Do not rely on the detail field for error handling; instead, rely on the code field.
field string, optional	Contains the name of the field that caused and / or is related to this error, in JSON dot notation format.

Retry Behaviors

All requests to the Cash App Pay API are idempotent, but you should only retry requests in certain cases. There are 3 types of retry behaviors documented below:

Retry Type	Description
Retryable	The error can be resolved by retrying the request as-is, possibly after waiting a short period of time. No changes to the request are necessary to retry and possibly get a different response. This retry behavior is typically associated with rate limiting, internal server errors, or waiting for automated state transitions.
Retryable with New Payload	The error can be resolved by retrying the request, but requires changing the request payload first. This retry behavior is typically associated with validation failures, where the API client isn’t sending valid data.
Permanent (Do Not Retry)	The error cannot be resolved by retrying the request in any capacity. This behavior is typically associated with payment or refund declines, where the API client sent a valid request, but Cash App Pay rejected it. The API client will need to create a new request and grant to proceed instead of attempting to modify/reuse an existing one.

For more information about handling errors in your code, see error handling.

Authentication Errors

The following errors occur before a request is processed by the Cash App API, during authentication and authorization. They are typically related to issues with the credentials passed to the API.

All validation errors have a category of AUTHENTICATION_ERROR.

Error Code	Description and Resolution
UNAUTHORIZED HTTP 401 Retryable with New Payload	The Cash App Pay API could not authenticate your request. This is typically due to: - Using sandbox credentials in production (or vice versa) - Using an invalid syntax for the authorization header - Using a mismatched client ID / API key pair To resolve this issue, double-check that you’ve set your credentials in the authorization header properly for the endpoint you’re calling. If you can’t resolve it with your existing credentials, reach out to Cash App Pay support and we’ll issue new credentials for you or look into why your requests aren’t being authenticated properly.
ACCESS_TOKEN_REVOKED HTTP 401 Retryable with New Payload	The client ID and API key provided were both valid and in the correct format, but the API key was revoked and may no longer be used to make calls. Refresh your API credentials to get a new API key and resolve this issue.
ACCESS_TOKEN_EXPIRED HTTP 401 Retryable with New Payload	The client ID and API key provided were both valid and in the correct format, but the API key has expired and may no longer be used to make calls. Refresh your API credentials to get a new API key and resolve this issue.
CLIENT_DISABLED HTTP 401 Retryable	The client ID and API key provided were both valid and in the correct format, but the API client has been disabled by Cash App Pay and is not allowed to make API calls. Reach out to Cash App Pay support if your API client has been improperly disabled, and they can get it re-enabled for you.
FORBIDDEN HTTP 403 Retryable with New Payload	The access token and client ID provided were valid, but don’t have access to the requested resource. Typically, this is caused by passing a resource ID that isn’t valid or managed by this API client.
INSUFFICIENT_SCOPES HTTP 403 Retryable with New Payload	The client ID and API key provided were both valid and in the correct format, and the client itself has access to the requested resource. However, this specific access token does not have the required permissions to perform the current action on the resource. Use a different API key that has permissions for the endpoint you’re calling to resolve this.

Validation Errors

The Cash App Pay API validates all requests sent by API clients to ensure they match the documented schemas. If a request does not match the schema, a validation error will be returned.

All validation errors have a category of INVALID_REQUEST_ERROR.

Do not automatically retry validation errors

Validation errors will continue to return the same error code if the API client continues to make requests with the same payload. Retrying the request will not change the response

General Validation Errors

Error Code	Description and Resolution
EXPECTED_JSON_BODY HTTP 400 Retryable with New Payload	The API client sent a request without a JSON payload to an endpoint that requires a payload, or the JSON provided in the payload was unparseable. The API client should make sure that it is passing a valid JSON payload to the endpoint. If you’re not sure if your JSON is valid, try using an online JSON validation tool (there are many of them) to give you feedback.
MISSING_REQUIRED_PARAMETER HTTP 400 Retryable	The API client did not provide a required query or body parameter. Refer to the `field` parameter on the error object to see which field should have been present, but was not found in the payload.
CONFLICTING_PARAMETERS HTTP 400 Retryable with New Payload	The API client sent a request payload that repeats parameters in the body that would overwrite each other (i.e., duplicate keys). Refer to the `field` parameter on the error object to see which field had duplicates in the request payload.
UNKNOWN_QUERY_PARAMETER HTTP 400 Retryable with New Payload	The API client sent a query parameter that does not exist in this version of the API. Refer to the `field` parameter on the error object to see which field could not be recognized. The Cash App Pay API returns errors for unknown fields to prevent API clients from setting a field that isn’t supported in a given API version, which could cause data integrity issues.
UNKNOWN_BODY_PARAMETER HTTP 400 Retryable with New Payload	The API client sent a field in the request payload that does not exist in this version of the API. Refer to the `field` parameter on the error object to see which field could not be recognized. The Cash App Pay API returns errors for unknown fields to prevent API clients from setting a field that isn’t supported in a given API version, which could cause data integrity issues.
INVALID_CONTENT_TYPE HTTP 400 Retryable with New Payload	The API client specified a Content-Type header on the request that is not supported by the endpoint. Two content types are used in the API: - application/json, the standard type for all endpoints except file uploads - multipart/form-data, for file uploads only; part of the request is a JSON payload, the other part is a binary representation of the file. The API client must set one of these content types as the header on each request. No other content types are accepted.
MISSING_REGION HTTP 400 Retryable with New Payload	The API client did not set the required X-Region header. The API uses regions to provide lower latencies for API clients, enforce idempotency, and respect data sovereignty. Regions (in the form of an IATA airport code) must be specified on each request using the X-Region header. See Regions and Localization for more information.
INVALID_REGION HTTP 400 Retryable with New Payload	The API client set the required X-Region header to an unrecognized code. The API client should change the X-Region header value to a valid code from the Regions and Localization page.
FEATURE_DISABLED HTTP 400 Retryable with New Payload	The API client set a field that requires a feature which is currently disabled for them. The API client should stop using the functionality described in the message of the error and reach out to Cash App Pay support to request access if necessary.

String Validation Errors

The following errors may occur when a request fails validation due to invalid data being passed to a field that accepts string values.

Error Code	Description and Resolution
EXPECTED_STRING HTTP 400 Retryable with New Payload	The API client passed a non-string value to a field that only accepts strings. Refer to the `field` parameter on the error object to see which field should have been a string, but received a different data type.
VALUE_TOO_LONG HTTP 400 Retryable with New Payload	The API client passed a string with too many characters to a field that has a maximum character length requirement. Refer to the `field` parameter on the error object to see which field had too many characters. The API documentation for that field should include the maximum character length it requires.
VALUE_TOO_SHORT HTTP 400 Retryable with New Payload	The API client passed a string with too few characters to a field that has a minimum character length requirement. Refer to the `field` parameter on the error object to see which field had too few characters. The API documentation for that field should include the minimum character length it requires.
VALUE_EMPTY HTTP 400 Retryable with New Payload	The API client passed an empty string or whitespace-only string to a field that requires a non-empty value. Refer to the `field` parameter on the error object to see which field failed validation. The API client must pass at least one non-whitespace character to pass this validation.
INVALID_TIME HTTP 400 Retryable with New Payload	The API client passed a value which could not be parsed by the server to a field accepting RFC-3339 formatted dates and / or timestamps, or the passed timestamp was not using UTC. Refer to the `field` parameter on the error object to see which field has an invalid date or timestamp. The API requires all time-related values to comply with RFC-3339, which is a more restrictive subset of the ISO-8601 standard: - Dates are formatted as YYYY-MM-DD. - Timestamps are formatted as YYYY-MM-DDTHH:MM:DDZ. Note that all timestamps must be in UTC time, or they will fail validation.
INVALID_EMAIL_ADDRESS HTTP 400 Retryable with New Payload	The API client passed a value which could not be parsed by the server to a field accepting well-formatted email addresses. Refer to the `field` parameter on the error object to see which field has an invalid email address. At a minimum, the API requires email addresses to contain at least one character followed by an @ sign and then at least one more character, i.e. a@b.
INVALID_PHONE_NUMBER HTTP 400 Retryable with New Payload	The API client passed a value which could not be parsed by the server to a `field` accepting well-formatted phone numbers. Refer to the `field` parameter on the error object to see which field has an invalid phone number. We recommend using libphonenumber to validate phone numbers before passing them to the API.
INVALID_URL HTTP 400 Retryable with New Payload	The API client passed a value which could not be parsed by the server to a field accepting well-formatted URL. Refer to the `field` parameter on the error object to see which field has an invalid URL. At a minimum, the API requires URLs to start with http:// or https:// and contain a domain and / or IP address.

Integer Validation Errors

The following errors may occur when a request fails validation due to invalid data being passed to a field that accepts integer values.

Error Code	Description and Resolution
EXPECTED_INTEGER HTTP 400 Retryable with New Payload	The API client passed a non-integer value to a field that only accepts integers. Refer to the `field` parameter on the error object to see which field should have been a integer, but received a different data type.
VALUE_TOO_HIGH HTTP 400 Retryable with New Payload	The API client passed a larger integer than allowed to an integer field. Refer to the `field` parameter on the error object to see which integer field requires a smaller value, then retry the request with a valid integer.
VALUE_TOO_LOW HTTP 400 Retryable with New Payload	The API client passed a smaller integer than allowed to an integer field. Refer to the `field` parameter on the error object to see which integer field requires a larger value, then retry the request with a valid integer.

Boolean Validation Errors

The following errors may occur when a request fails validation due to invalid data being passed to a field that accepts boolean values.

Error Code	Description and Resolution
EXPECTED_BOOLEAN HTTP 400 Retryable with New Payload	The API client passed a non-boolean value to a field that only accepts booleans. Refer to the `field` parameter on the error object to see which field should have been a boolean, but received a different data type.

Array Validation Errors

The following errors may occur when a request fails validation due to invalid data being passed to a field that accepts array values.

Error Code	Description and Resolution
EXPECTED_ARRAY HTTP 400 Retryable with New Payload	The API client passed a non-array value to a field that only accepts arrays. Refer to the `field` parameter on the error object to see which field should have been an array, but received a different data type.
ARRAY_LENGTH_TOO_LONG HTTP 400 Retryable with New Payload	The API client passed more than the minimum number of elements to an array field. Refer to the `field` parameter on the error object to see which array field requires fewer elements.
ARRAY_LENGTH_TOO_SHORT HTTP 400 Retryable with New Payload	The API client passed fewer than the minimum number of elements to an array field. Refer to the `field` parameter on the error object to see which array field requires additional elements.
INVALID_ARRAY_TYPE HTTP 400 Retryable with New Payload	The API client passed an array to an array field, which is valid, but the data type within the array did not match the expected data type. Refer to the `field` parameter on the error object to see which array field has an invalid data type, then use the detail field to see what the correct data type is.

Object Validation Errors

The following errors may occur when a request fails validation due to invalid data being passed to a field that accepts nested objects.

Error Code	Description and Resolution
EXPECTED_OBJECT HTTP 400 Retryable with New Payload	The API client passed a non-object value to a field that only accepts objects. Refer to the `field` parameter on the error object to see which field should have been an object, but received a different data type.

Map Validation Errors

The following errors may occur when a request fails validation due to invalid data being passed to a field that accepts maps.

Error Code	Description and Resolution
TOO_FEW_MAP_ENTRIES HTTP 400 Retryable with New Payload	The API client did not add enough keys to the map. Refer to the `field` parameter on the error object to see which field was not provided with enough keys.
TOO_MANY_MAP_ENTRIES HTTP 400 Retryable with New Payload	The API client added too many keys to the map. Refer to the `field` parameter on the error object to see which field has too many map keys.

Common Runtime Errors

The following error codes are re-used throughout the Cash App Pay API and handle common errors, such as missing resources, pagination problems, and idempotency key reuse.

All of the following errors have a category of INVALID_REQUEST_ERROR.

Error Code	Description and Resolution
NOT_FOUND HTTP 404 Retryable with New Payload	The API client requested a resource that could not be found or isn’t owned by the client. The API client should ensure that it is passing the correct ID in the request. Unless the ID parameter is changed, the endpoint will continue to respond with a “not found” error and the client should not retry the request.
CONFLICT HTTP 409 Retryable	The action to perform on the resource cannot be completed due to a conflict with the current state of the resource or its related resources.
INVALID_CURSOR HTTP 400 Retryable with New Payload	The API client provided a cursor to a paginated endpoint that could not be parsed by the API.The API client should ensure that it is passing the correct cursor in the request. If the API client can’t identify a valid cursor to provide, it should restart pagination by passing a blank cursor in the request and getting a new, valid cursor from the response. Unless the cursor parameter is changed, the endpoint will continue to respond with an “invalid cursor” error and the client should not retry the request.
IDEMPOTENCY_KEY_REUSED HTTP 400 Retryable with New Payload	The idempotency key provided by the API client has already been used with a different request payload on this endpoint. The API client must retry the request with a different idempotency key.
INVALID_STATE_TRANSITION HTTP 400 Retryable with New Payload	The API client is attempting a change not allowed by the state machine for the resource. This error indicates that the API client is referring to stale data or has a bug in its business logic. The API client should not retry the request.
CLIENT_NOT_FOUND HTTP 400 Retryable with New Payload	The API client passed a client ID value in the request payload that did not match the API client’s ID, OR no client could be found for the given client ID in the request payload. The API client must retry the request with a different (and valid) client ID.
IDEMPOTENCY_PAYLOAD_MISMATCH HTTP 400	A previous idempotency key was already used to perform an action on the given resource with the given payload. The action cannot be performed again with a new idempotency key.

Rate Limit Errors

The Cash App Pay API rate limits OLAP (online analytical processing) requests to guarantee that the Cash App Pay service stays fast and stable. These include operations such as:

Listing payments for an API client by reference ID
Retrieving a list of active grants approved by a given customer
…and any other “list” or “search” endpoints in the API

Reach out to Cash App Pay support at any time to request rate limit increases on these endpoints, and we will be happy to adjust them for you.

Payment processing requests are never rate-limited

OLTP (online transaction processing) requests related to payment acceptance are never rate-limited. This includes, but is not limited to:

Creating, reading, voiding, and capturing individual Payments
Creating, reading, voiding, and capturing individual Refunds
Creating, upserting, reading, and updating individual Bbrands
Creating, upserting, reading, and updating individual Merchants
Creating, reading, and updating Customer Requests
Reading and revoking Individual Grants

Refer to the API reference pages for any endpoint to see if it’s rate limited.

Error Code	Description and Resolution
RATE_LIMITED HTTP 429 Retryable	The API client is making too many requests too quickly and should reduce the number of calls it’s making to the API. Rate-limited requests are not checked for validity, so errors may be encountered when they are retried later on. The API client should retry the requests at a slower pace using exponential backoff.

Payment Processing Errors

The following error codes may occur in payment processing flows. In addition to these errors, grant errors may occur during payment processing, while using grants to create a payment.

All payment processing errors have a category of PAYMENT_PROCESSING_ERROR.

Error Code	Description and Resolution
MERCHANT_NOT_FOUND HTTP 400 Retryable with New Payload	The API client provided a merchant ID in the request that could not be found or isn’t owned by the client. The API client should ensure that it is passing the correct merchant ID in the request. Unless the merchant ID parameter is changed, the endpoint will continue to respond with a “not found” error and the client should not retry the request.
PAYMENT_NOT_FOUND HTTP 400 Retryable with New Payload	The API client provided a payment ID or idempotency key in the request that could not be found or isn’t owned by the client. The API client should ensure that it is passing the correct payment ID or idempotency key in the request. Unless the payment ID or idempotency key parameter is changed, the endpoint will continue to respond with a “not found” error and the client should not retry the request.
REFUND_NOT_FOUND HTTP 400 Retryable with New Payload	The API client provided a refund ID or idempotency key in the request that could not be found or isn’t owned by the client. The API client should ensure that it is passing the correct refund ID or idempotency key in the request. Unless the refund ID or idempotency key parameter is changed, the endpoint will continue to respond with a “not found” error and the client should not retry the request.
CUSTOMER_DISABLED HTTP 400 Permanent (Do Not Retry)	The customer the API client is trying to take a payment or issue a refund for is deactivated in Cash App Pay and cannot send or receive funds. The payment or refund is declined. The API client should consider this a permanent decline. Retrying the request will not change the response. Grants are consumed by this decline.
MERCHANT_DISABLED HTTP 400 Retryable	The merchant the API client is trying to take a payment or issue a refund for is deactivated in Cash App Pay and cannot send or receive funds. The payment or refund is declined. The API client should consider this a retryable decline. Retrying the request when a merchant has become active will change the response. Grants are not consumed by this decline. Merchants can be deactivated by Cash App or by the API client. API client-initiated deactivations can be reversed using the UpdateMerchant endpoint. Cash App-initiated deactivations are permanent and cannot be reversed.
MERCHANT_PENDING HTTP 400 Retryable	The merchant the API client is trying to take a payment or issue a refund for is still being onboarded to Cash App Pay. The API client should consider this a retryable decline. Retrying the request once the merchant is active will change the response. Grants are not consumed by this decline. The API client must wait for the merchant to move from a status of PENDING to ACTIVE before using it to take payments or issue refunds. This generally happens within 15 minutes of merchant creation, but may take longer in rare cases.
PAYMENT_DECLINED_COMPLIANCE HTTP 400 Permanent (Do Not Retry)	Cash App Pay detected a violation of terms of service, Program Rules, or applicable laws for the payment the API client is trying to create or capture. The payment is declined. The API client should consider this a permanent decline. Retrying the request will not change the response. Grants are consumed by this decline. No detail will be given as to what caused the compliance decline in the API; reach out to Cash App Pay support if you need to know more about an individual decline.
PAYMENT_DECLINED_INSUFFICIENT_FUNDS HTTP 400 Permanent (Do Not Retry)	The customer the API client is attempting to take a payment from does not have sufficient funds to complete the payment. The API client should consider this a permanent decline. Retrying the request will not change the response. Grants are consumed by this decline.
PAYMENT_DECLINED_LIMIT_REACHED HTTP 400 Permanent (Do Not Retry)	The customer the API client is attempting to take a payment from has reached the maximum amount of money they’re allowed to spend from their account in a given time period. The API client should consider this a permanent decline. Retrying the request will not change the response. Grants are consumed by this decline.
PAYMENT_DECLINED_OTHER HTTP 400 Permanent (Do Not Retry)	The API declined the payment for an unknown reason. Used as a fallback when a more specific reason is not applicable. The API client should consider this a permanent decline. Retrying the request will not change the response. Grants are consumed by this decline.
PAYMENT_DECLINED_RISK HTTP 400 Permanent (Do Not Retry)	Cash App Pay detected this payment as having a high likelihood of fraud. The payment is declined. The API client should consider this a permanent decline. Retrying the request will not change the response. Grants are consumed by this decline. No detail will be given as to what caused the risk decline in the API; reach out to Cash App Pay support if you need to know more about an individual decline.
PAYMENT_DECLINED_CUSTOMER_BLOCKED_MERCHANT HTTP 400 Permanent (Do Not Retry)	The customer the API client is attempting to take a payment from has blocked the merchant from sending them payments. The payment is declined. The API client should consider this a permanent decline. Retrying the request will not change the response. Reach out to Cash App Pay support if you need to know more about an individual decline.
PAYMENT_INVALID_AMOUNT_MISMATCH HTTP 400 Retryable with New Payload	The amount the API client intended to created the payment with did not match the amount shown to the customer during the customer request for payment. The API client should consider this a retryable decline. Retrying the request with an amount that matches the one shown on the customer request will change the response. Grants are not consumed by this decline.
PAYMENT_INVALID_CURRENCY_MISMATCH HTTP 400 Retryable with New Payload	The currency the API client intended to created the payment with did not match the currency shown to the customer during the customer request for payment, or the currency of the merchant did not match the payment’s currency. The API client should consider this a retryable decline. Retrying the request with a currency that matches the one shown on the customer request and the one on the merchant will change the response. Grants are not consumed by this decline.
PAYMENT_INVALID_TOO_LARGE HTTP 400 Retryable with New Payload	The API declined the payment due to the amount being too high. The maximum payment size may be adjusted to prevent fraud, though this is not equivalent to a risk decline. The API client should consider this a retryable decline. Retrying the request with a lower amount may change the response. Grants are not consumed by this decline.
PAYMENT_INVALID_TOO_SMALL HTTP 400 Retryable with New Payload	The API declined the payment due to the amount being too low (below $0.01 USD). The API client should consider this a retryable decline. Retrying the request with a larger amount may change the response. Grants are not consumed by this decline.
REFUND_DECLINED_COMPLIANCE HTTP 400 Permanent (Do Not Retry)	Cash App Pay detected a violation of terms of service, Program Rules, or applicable laws for the refund the API client is trying to create or capture. The refund is declined. The API client should consider this a permanent decline. Retrying the request will not change the response. Grants are consumed by this decline. No detail will be given as to what caused the compliance decline in the API; reach out to Cash App Pay support if you need to know more about an individual decline.
REFUND_DECLINED_OTHER HTTP 400 Permanent (Do Not Retry)	The API declined the refund for an unknown reason. Used as a fallback when a more specific reason is not applicable. The API client should consider this a permanent decline. Retrying the request will not change the response. Grants are consumed by this decline.
REFUND_DECLINED_RISK HTTP 400 Permanent (Do Not Retry)	Cash App Pay detected this refund as having a high likelihood of fraud. The payment is declined. The API client should consider this a permanent decline. Retrying the request will not change the response. Grants are consumed by this decline. No detail will be given as to what caused the risk decline in the API; reach out to Cash App Pay support if you need to know more about an individual decline.
REFUND_INVALID_CURRENCY_MISMATCH HTTP 400 Retryable with New Payload	The currency the API client intended to create the refund with is invalid for one or more of the following reasons: - The currency of the merchant does not match the currency of the refund - The currency of the payment being refunded does not match the currency of the refund The API client should consider this a retryable decline. Retrying the request with a correctly-matched currency changes the response.
REFUND_INVALID_PAYMENT_UNCAPTURED HTTP 400 Retryable with New Payload	The API declined the refund because the linked payment has not been captured. The API client should void the original payment instead of issuing a refund.
REFUND_INVALID_TOO_LARGE HTTP 400 Retryable with New Payload	The API declined the payment due to the amount being too high. This could be due to a disputed payment which the merchant lost. The maximum payment size can be adjusted to prevent fraud, though this is not equivalent to a risk decline. The API client should consider this a retryable decline. Retrying the request with a lower amount may change the response. Grants are not consumed by this decline.
REFUND_INVALID_TOO_SMALL HTTP 400 Retryable with New Payload	The API declined the refund due to the amount being too low (below $0.01 USD). The API client should consider this a retryable decline. Retrying the request with a larger amount may change the response. Grants are not consumed by this decline.
REFUND_INVALID_SCOPE_MISMATCH HTTP 400	A payment/refund cannot be processed for this client because it has missing bank account configurations necessary for settlement purposes.
MISSING_SETTLEMENT_CONFIGURATION HTTP 400	A payment/refund cannot be processed for this client because it has missing configurations necessary for reporting purposes.

Payouts

The following error codes may occur while creating payouts. All payout errors have a category of PAYOUT_PROCESSING_ERROR.

Error Code	Description and Resolution
PAYOUT_DECLINED_INSUFFICIENT_FUNDS HTTP 400 Retryable	The merchant does not have sufficient funds or collateral for the payout. The API client should consider this a retryable decline. Retrying the payout after the merchant’s balance or collateral situation is resolved may change the response. If this error is returned by Create payout, the payout is still created with a `DECLINED` status. One-time grants are consumed by `PAYOUT_DECLINED_*` errors, so the API client must repeat the Customer Request flow to obtain a new grant before retrying.
PAYOUT_INVALID_CURRENCY HTTP 400 Retryable with New Payload	The payout was created with an unsupported currency. The API client should retry the request with a supported currency. `PAYOUT_DECLINED_*` errors consume one-time grants; other payout errors do not.
PAYOUT_DECLINED_RISK HTTP 400 Permanent (Do Not Retry)	Cash App Pay declined the payout due to fraud or other risky activity. The API client should consider this a permanent decline. Retrying the request will not change the response. If this error is returned by Create payout, the payout is still created with a `DECLINED` status and the one-time grant is consumed. No detail will be given as to what caused the risk decline in the API; reach out to Cash App Pay support if you need to know more about an individual decline.
PAYOUT_DECLINED_OTHER HTTP 400 Permanent (Do Not Retry)	The payout was declined for an unknown reason. Used as a fallback when a more specific reason is not applicable. The API client should consider this a permanent decline. Retrying the request will not change the response. If this error is returned by Create payout, the payout is still created with a `DECLINED` status and the one-time grant is consumed.
PAYOUT_DECLINED_LIMIT_REACHED HTTP 400 Permanent (Do Not Retry)	The payout was declined because the customer or merchant has reached a payout limit for the current time period. The API client should consider this a permanent decline. Retrying the request will not change the response. If this error is returned by Create payout, the payout is still created with a `DECLINED` status and the one-time grant is consumed.

Merchant & Brand Registration Errors

The following error codes may occur while managing merchants and brands on Cash App Pay.

All merchant registration errors have a category of MERCHANT_ERROR or BRAND_ERROR.

Error Code	Description and Resolution
BRAND_NOT_FOUND HTTP 400 Retryable with New Payload	The API client provided a brand ID in the request that could not be found or isn’t owned by the client. The API client should ensure that it is passing the correct brand ID in the request. Unless the brand ID parameter is changed, the endpoint will continue to respond with a “not found” error and the client should not retry the request.
MERCHANT_MISSING_ADDRESS_OR_SITE HTTP 400 Retryable with New Payload	The API client tried to create or update a merchant and set both the address and site URL fields to null. Merchants require an address or site URL. The API client should set an address or site URL in the payload to resolve this error, then retry the request.

Grant Errors

The following error codes may occur while using any endpoint that interacts with grants, including ones used to create payments or refunds.

All grant errors have a category of GRANT_ERROR.

Error Code	Description and Resolution
GRANT_ACTION_TYPE_MISMATCH HTTP 400 Retryable with New Payload	The API found the provided grant and attempted to use it, but failed due to the grant’s action not being compatible with the endpoint being called. The grant was not consumed. The API client should send the customer through the customer request flow with the correct action type for the endpoint it wants to call and generate a valid grant.
GRANT_CONSUMED HTTP 400 Retryable with New Payload	The API found the provided grant and attempted to use it, but failed due to the grant being previously used (for one-time grants). The API client should send the customer through the customer request flow again to generate a fresh, unused, grant.
GRANT_EXPIRED HTTP 400 Retryable with New Payload	The API found the provided grant and attempted to use it, but failed due to the grant having expired. The API client should send the customer through the customer request flow again to generate a fresh grant.
GRANT_NOT_FOUND HTTP 400 Retryable with New Payload	The API client provided a grant ID in the request that could not be found or isn’t owned by the client. The API client should ensure that it is passing the correct grant ID in the request. Unless the grant ID parameter is changed, the endpoint will continue to respond with a “not found” error and the client should not retry the request.
GRANT_REVOKED HTTP 400 Retryable with New Payload	The API found the provided grant and attempted to use it, but failed due to the grant having been revoked. The API client should send the customer through the customer request flow again to generate a fresh grant.

Dispute Errors

The following error codes may occur while using any endpoint that responds to disputes.

All dispute errors have a category of DISPUTE_ERROR.

Error Code	Description and Resolution
DISPUTE_MISSING_EVIDENCE HTTP 400 Retryable	The request to challenge the dispute was valid and a dispute existed for the provided ID, but no evidence was found to challenge the dispute with. Since no evidence results in an automatic loss of the dispute, API clients are not allowed to “challenge” a dispute without evidence. If you want to respond to a dispute with no evidence, you should instead call the AcceptDispute endpoint, which makes the intent to “lose” the dispute explicit. Otherwise, upload evidence for the dispute and then re-attempt challenging it.

Error Code

Description and Resolution

DISPUTE_MISSING_EVIDENCE
HTTP 400
Retryable

Webhook Errors

The following error codes may occur while using any webhook related endpoints.

All webhook errors have a category of WEBHOOK_ERROR.

Error Code	Description and Resolution
WEBHOOK_ENDPOINT_NOT_FOUND HTTP 400 Retryable with New Payload	The API client provided a webhook endpoint ID in the request that could not be found or isn’t owned by the client. The API client should ensure that it is passing the correct webhook endpoint ID in the request. Unless the webhook endpoint ID parameter is changed, the endpoint will continue to respond with a “not found” error and the client should not retry the request.
WEBHOOK_ENDPOINT_TOO_MANY HTTP 400	The maximum number of webhook endpoints for the client has been reached. Delete existing webhook endpoints before trying to create new ones.

Customer Errors

The following error codes may occur while using any customer-related endpoints.

All customer errors have a category of CUSTOMER_ERROR.

Error Code	Description and Resolution
CUSTOMER_DELETED_ACCOUNT HTTP 400 Permanent (Do Not Retry)	The customer account has been deleted. This is a permanent operation that cannot be revoked.

API Errors

In the rare event that the Cash App Pay APIs experience issues, the error codes below will be returned.

All server errors (ones not caused by the API client) have a category of API_ERROR.

Error Code	Description and Resolution
INTERNAL_SERVER_ERROR HTTP 500 Retryable	A general server error occurred, due to an issue with the API. The API client should retry its request. If errors continue, reach out to Cash App Pay support.
SERVICE_UNAVAILABLE HTTP 503 Retryable	The API being called is experiencing an outage. The API client should retry its request. If errors continue, reach out to Cash App Pay support.
GATEWAY_TIMEOUT HTTP 504 Retryable	The API was unable to process the request in a reasonable period of time and terminated the request. The API client should retry its request. If errors continue, reach out to Cash App Pay support.