Response Codes - Retail APIs

All Retail API responses include a responseCode field. This page is the authoritative reference for all codes returned across all endpoints.

A responseCode of 0 always indicates success. Non-zero codes indicate either a partial success (code 1) or an error condition. The responseDescription field provides additional context specific to the individual request — treat it as a sub-message, not a substitute for the numeric responseCode.

No subcodes: The Retail API does not use numeric subcodes. The responseCode is the primary classification; responseDescription is the free-text detail.

HTTP Status Codes

The Retail API uses HTTP 200 OK for all responses — including application-level errors. The responseCode field inside the response body is the authoritative indicator of success or failure, not the HTTP status code.

The one exception is authentication:

HTTP Status	When It Occurs	Resolution
`401 Unauthorized`	Bearer token is missing, expired, or issued for a different application. No response body is returned.	Regenerate your access token and retry the request. See Getting Started.

Any other HTTP-level failure (e.g., 404, 503) indicates a network or configuration issue (wrong base URL, allowlist not configured, environment outage) rather than an application error.

Application Response Codes

Code	Code Text	Description	Resolution
0	Success	Request processed successfully.	No action needed.
1	SuccessFundingDelay	Transaction succeeded but funds will not be available until the funding delay window (`fundingDelaySeconds`) elapses. Applicable to Reload and Barcode Payment.	No action needed. Display `receiptText` to the customer and advise them funds will be available shortly. The transaction may be voided within the `fundingDelaySeconds` window if needed.
100	InvalidParameter	A required parameter is missing or a parameter value failed validation. The `responseDescription` specifies which parameter failed.	Inspect `responseDescription` to identify the failing field. Correct the value and retry.
110	InvalidAccount	The card account was not found, account status is not valid (e.g., Closed, Pending, Blocked), or the account is not reloadable for the current partner.	Ask the customer to verify the card number. If the number is correct, the customer should contact their card provider to check account status.
130	InvalidMerchant	The `merchantId` in the request was not found or has not been enabled in the system.	Verify the `merchantId` value matches the credential provisioned by Green Dot. If correct, contact your Green Dot account manager — the merchant may not be enabled.
140	InvalidBarcode	Barcode not found, or barcode status is not valid. Possible statuses: Pending Consumption, Already Consumed, Declined, Voided, Expired.	Ask the customer to verify the barcode. If expired or already used, the customer should generate a new barcode from their app or provider.
150	InvalidPin	PIN not found or PIN status is not valid.	Verify the PIN. If the issue persists, contact your Green Dot account manager.
451	SoftDeclineVerifyPending	Identity verification is pending for this account.	Contact your Green Dot account manager for details on this account's verification status.
453	CustomerHasSsn	Account has an SSN on file that conflicts with this operation.	Contact your Green Dot account manager to determine the appropriate next step.
460	OperationNotAllowed	The requested operation is not permitted for this card or request type. For Point of Banking Payment, this may indicate an invalid initial load attempt.	Verify the transaction type is supported for this card. For Point of Banking, confirm the card is eligible and the flow is correct. Contact your Green Dot account manager if the issue persists.
500	CIPFailed	Customer Identification Program (CIP) verification failed for this transaction.	The customer must contact their card provider to resolve their identity verification status before this transaction can be processed.
600	UnableToProcessRequest	Unable to process the request. Common causes: fee split not configured, duplicate transaction detected, or a downstream service error. Duplicate transactions are declined; the original transaction remains valid.	Inspect `responseDescription`. If the cause is a duplicate transaction, do not retry — the original transaction is still valid. For fee split errors, contact your Green Dot account manager. For other causes, retry with a new unique `X-GD-RequestId`.
700	LoadLimitValidationFailed	The transaction amount does not pass load limit validation. May be a per-transaction limit, account balance limit, or daily reload limit. The `responseDescription` specifies the applicable limit range.	Inspect `responseDescription` for the allowed amount range. Reduce the transaction amount to within the stated limits and retry, or advise the customer to try again tomorrow if a daily limit has been reached.
800	InvalidStore	The store was not found, is not associated with this partner, or does not support this operation.	Verify the `storeId` value is correct. If correct, contact your Green Dot account manager to confirm the store is enrolled and enabled for this transaction type.
801	StoreBlocked	The store has been blocked by Green Dot store blocker rules.	Contact your Green Dot account manager to investigate the block and determine resolution.
815	AccountNotFound	The specified account could not be found.	Verify the account identifier in the request. If the identifier is correct, advise the customer to contact their card provider.
823	CardStatusInvalid	The card's current status does not permit this operation.	Advise the customer to contact their card provider to check and resolve the card status.
840	TransactionNotFound	No matching transaction found for the provided `originalTransactionId`, or the original transaction belongs to a different store or partner.	Verify the `originalTransactionId` value matches the `X-GD-RequestId` used in the original transaction, and that the void is being submitted from the same store and merchant.
841	NotVoidableTransactionType	The transaction type cannot be voided. Only `Reload` and `Sale` transaction types support voids.	No void is possible for this transaction type. If the customer needs a refund, direct them to their card provider.
842	TransactionAlreadyVoided	The transaction has already been voided.	No action needed — the void was already processed.
843	TransactionAlreadyPosted	The transaction has been posted (committed) and can no longer be voided. The funding delay window has elapsed.	Void is no longer possible. If the customer needs a refund, direct them to their card provider.
844	NotVoidableTransactionStatus	The transaction's current status does not permit a void.	Void is not possible in the transaction's current state. Contact your Green Dot account manager if further action is needed.
848	TransactionAlreadyReturned	The transaction has been returned and cannot be voided.	No action needed — the transaction was already returned.
860	ErrorUpdateTeller	An error occurred updating the teller record for this transaction.	Retry the request. If the error persists, contact your Green Dot account manager.
861	RetailChainUserNotFound	The specified retail chain user was not found.	Verify the `userId` value in the request. Contact your Green Dot account manager if the issue persists.
862	RetailChainUserNotActive	The retail chain user exists but is not active.	Contact your Green Dot account manager to activate the user account.
863	UserNameNotMatch	The provided username does not match the record on file.	Verify the `userId` value. Contact your Green Dot account manager if the issue persists.
868	SameCardIsNotAllowed	The same card was used in a context where it is not permitted (e.g., source and destination card are identical).	Advise the customer to use a different card for this transaction.
870	ChangeFeePlanFailed	Updating the fee plan for this account failed.	Contact your Green Dot account manager to investigate the fee plan configuration.
871	RetailChainUserCreated	A retail chain user record was created as part of this transaction.	Informational — no action required.
872	RetailChainUserUpdated	A retail chain user record was updated as part of this transaction.	Informational — no action required.
999	RequestTimeout	The request expired or no response was received from a downstream service within the allowed time period.	Retry the request with a new unique `X-GD-RequestId`. Do not reuse the original ID — it may still be in flight. If timeouts persist, contact your Green Dot account manager.
1000	GeneralFailure	An unspecified service failure occurred.	Retry the request with a new unique `X-GD-RequestId`. If the error persists across multiple attempts, contact your Green Dot account manager.

Notes on Error Handling

HTTP vs. application errors: Always check the HTTP status code first. A 401 means your token needs to be regenerated before making any further requests. For all other responses (HTTP 200), evaluate responseCode to determine outcome.

Duplicate transaction detection: If a request is retried with the same X-GD-RequestId, the system may return 600 UnableToProcessRequest with a duplicate indication in responseDescription. Always generate a new unique X-GD-RequestId for each attempt.

Token expiry: A 401 Unauthorized with no response body means the Bearer token is invalid, expired, or mismatched. Regenerate the token and retry — do not retry with the same token.

Retry guidance: 999 RequestTimeout and 1000 GeneralFailure are safe to retry with a new X-GD-RequestId. For all other non-zero codes, inspect responseDescription, correct the underlying issue, and only then retry.

Informational codes: Codes 871 (RetailChainUserCreated) and 872 (RetailChainUserUpdated) are informational status codes that may be returned alongside a successful transaction. No partner action is required.