Error codes

Learn more about common error codes.

Affirm uses HTTP response status codes to indicate the success or failure of your API requests. If your request fails, Affirm returns an error using the appropriate status code.

In general, there are three status code ranges you can expect:


2xx success status codes confirm that your request worked as expected.


4xx error status codes indicate an error because of the information provided (e.g., a required parameter was omitted).


5xx error status codes are rare and indicate an error with Affirm's servers.

Some 4xx errors that could be handled programmatically include an error code—a short string with a brief explanation—as a value for code. Below is a list of possible error codes that can be returned, along with additional information.

Error codesDescription
auth-declinedCharge authorization hold declined.
capture-greater-instrumentCannot capture charges on this instrument for more than the authorization hold amount.
capture-unequal-instrumentCannot capture charges on this instrument for an amount unequal to the authorization hold amount.
capture-voidedCannot capture voided charge.
partial-capture-instrumentCannot partially capture charges on this instrument.
refund-exceededExceeded maximum refund.
refund-uncapturedCannot refund a charge that has not been captured.
refund-voidedCannot refund a voided charge.
capture-declinedCharge capture declined.
capture-limit-exceededExceed maximum capture amount on charge.
expired-authorizationCannot capture a charge with an expired authorization hold.
refund-expiredCharges on this instrument must be refunded within N days of capture.
invalid_fieldAn input field resulted in invalid request.
public-api-key-not-specifiedPlease provide a public API key.
public-api-key-invalidPlease provide a valid public API key.
public-api-key-wrong-environmentPlease provide a live public API key when not using the sandbox environment.
public-api-key-inactivePlease provide an active public API key.
api-key-pair-not-specifiedPlease provide an API key pair.
private-api-key-invalidPlease provide a valid private API key.
api-key-pair-wrong-environmentPlease provide a live API key pair when not using the sandbox environment.
api-key-pair-inactivePlease provide an active API key pair.
not_foundCould not find the resource(s) specified in the request.