Affirm's APIs use conventional HTTP status codes to indicate the success or failure of API requests.
API calls successfully made to Affirm use codes in the 2xx range while codes in the 4xx range indicate failure and codes in the 5xx range internal server issues.
When an API call fails, the response body contains the error code, an error object, as well as additional information about the error to help you identify and resolve the issue.
Some 4xx errors that could be handled programmatically (e.g., a capture declined) include an error code that briefly explains the error reported.
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.
Field Names
| Key | Data type | Description |
|---|---|---|
| status_code | string | The returned HTTP status code. |
| message | string | A friendly and human-readable message providing more details about the error. |
| code | string | A short code reference, such as a three-digit number, that identifies a specific error and can be used programmatically. |
| type | string | The category of error being returned that can be used programmatically. |
| field | string | An incorrect or invalid value. |
Status Codes
Charges endpoint status codes
| Status Codes | Error Message |
|---|---|
| 200 - Success | The API call worked as expected. |
| 400 - Bad request | The request was improper. This is often due to missing information in the request fields. |
| 401 - Unauthorized | No valid API key provided |
| 402 - Request failed | The parameters were valid but the request failed. |
| 404 - Not found | The requested resource could not be found. |
| 409 - Conflict | - Charges on this instrument cannot be captured for an amount that is greater than the total capturable balance. - Charges on this instrument cannot be captured for an amount unequal to authorization hold amount. - Charges on this instrument cannot be captured for an amount that is not equal to the total capturable balance. - The transaction with this idempotency key is processing. Please wait to retry or use a different idempotency key. |
| 500, 502, 503, 504 - Server Errors | Something went wrong on Affirm's end. Please check our status page. |
Transactions endpoint status codes
Expanded error handling
The
TransactionsAPI has specific error codes depending on the API call.
POST Capture Transaction
| Status Code | Error Message |
|---|---|
| 403 - Forbidden error | - The transaction cannot be captured or refunded while it is disputed. - The idempotency key provided has already been used. - The transaction is past its capturable period and cannot be captured. Please contact [email protected] for assistance. - The transaction has been voided and may no longer be captured. - The transaction has already been voided. - The transaction must be authorized before it may be captured. |
| 404 - Not found | The transaction could not be found. |
| 409 - Conflict | - Charges on this instrument cannot be captured for an amount that is greater than the total capturable balance. - Charges on this instrument cannot be captured for an amount unequal to authorization hold amount. - Charges on this instrument cannot be captured for an amount that is not equal to the total capturable balance. - The transaction with this idempotency key is processing. Please wait to retry or use a different idempotency key. |
POST Refund Transaction
| Status Code | Error Message |
|---|---|
| 403 - Forbidden error | - The transaction cannot be captured or refunded while it is disputed. - Refund amount is required for a partially refunded transaction.- The refund amount exceeds the remaining loan balance. - The idempotency key provided has already been used. - This transaction cannot be refunded while the refund amount is negative. - The transaction is on the Virtual Card Network and may not be refunded by the Transaction API. - The transaction is authorized and may not be refunded. Try voiding the transaction instead. - The transaction has been voided and cannot be refunded. - The transaction is past its refundable period and cannot be refunded. Please contact [email protected] for assistance. |
| 404 - Not found | The transaction could not be found. |
| 409 - Conflict | The transaction with this idempotency key is processing. Please wait to retry or use a different idempotency key. |
POST Void Transaction
| Status Code | Error Message |
|---|---|
| 403 - Forbidden error | - The transaction cannot be captured or refunded while it is disputed. - Refund amount is required for a partially refunded transaction.- The refund amount exceeds the remaining loan balance. - The idempotency key provided has already been used. - This transaction cannot be refunded while the refund amount is negative. - The transaction is on the Virtual Card Network and may not be refunded by the Transaction API. - The transaction is authorized and may not be refunded. Try voiding the transaction instead. - The transaction has been voided and cannot be refunded. - The transaction is past its refundable period and cannot be refunded. Please contact [email protected] for assistance. |
| 404 - Not found | The transaction could not be found. |
| 409 - Conflict | - Void amount is not allowed for a merchant not supporting split capture. - The total amount to be voided cannot be greater than the total capturable balance. - The transaction with this idempotency key is processing. Please wait to retry or use a different idempotency key. |
Error Types
| Error Types | Description |
|---|---|
invalid_field | One or more fields contains an invalid value (e.g., invalid currency). |
invalid_request | A generic error that indicates invalid request inputs. |
unauthorized | Invalid API keys provided. |
Error Codes
| Error codes | Description |
|---|---|
already_captured | The transaction has already been captured. |
api-key-pair-invalid | - Please provide a public API key. - Please provide a valid public API key. - Please provide a valid private API key. - Please provide an active public API key. - Please provide an API key pair. - Please provide an active API key pair. |
api-key-pair-wrong-environment | - Please provide a live public API key when not using the sandbox environment. - Please provide a live API key pair when not using the sandbox environment. |
authorize_forbidden_on_declined | Charge authorization hold declined. |
authorize_period_expired | Cannot capture a charge with an expired authorization hold. |
capture_declined | Charge capture declined. |
capture_forbidden_on_voided | Cannot capture voided charge. |
capture_greater_than_auth | Cannot capture charges on this instrument for more than the authorization hold amount. |
capture_greater_than_balance | Exceed maximum capture amount on charge. |
capture_not_equal_to_auth | Cannot capture charges on this instrument for an amount unequal to the authorization hold amount. |
invalid_request | An input field resulted in invalid request. |
must_be_authorized_to_capture | The transaction must be authorized to capture. |
not_found | Could not find the resource(s) specified in the request. |
refund_exceeds_charge | Exceeded maximum refund. |
refund_forbidden_on_authorized | Cannot refund a charge that hasn't been captured. |
refund_forbidden_on_voided | Cannot refund a voided charge. |
refund_period_expired | Charges on this instrument must be refunded within N days of capture. |
void_amount_invalid | The total amount to be voided must be between zero and the total capturable balance. |
void_forbidden_on_captured | The transaction has been captured and may no longer be voided. |