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.
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 for the specific error that can be used programmatically. |
type | string | The type 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 |
|
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
Transactions
API has specific error codes depending on the API call.
POST Capture Transaction
Status code | Error message |
---|---|
403 - Forbidden error |
|
404 - Not found | The transaction could not be found. |
409 - Conflict |
|
POST Refund Transaction
Status code | Error message |
---|---|
403 - Forbidden error |
|
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 |
|
404 - Not found | The transaction could not be found. |
409 - Conflict |
|
Error types
Error types | Description |
---|---|
| Invalid API keys provided. |
| A generic error that indicates invalid request inputs. |
Error codes
Error codes | Description |
---|---|
| Charge authorization hold declined. |
| Cannot capture charges on this instrument for more than the authorization hold amount. |
| Cannot capture charges on this instrument for an amount unequal to the authorization hold amount. |
| Cannot capture voided charge. |
| Cannot partially capture charges on this instrument. |
| Exceeded maximum refund. |
| Cannot refund a charge that hasn't been captured. |
| Cannot refund a voided charge. |
| Charge capture declined. |
| Exceed maximum capture amount on charge. |
| Cannot capture a charge with an expired authorization hold. |
| Charges on this instrument must be refunded within N days of capture. |
| An input field resulted in invalid request. |
| Please provide a public API key. |
| Please provide a valid public API key. |
| Please provide a live public API key when not using the sandbox environment. |
| Please provide an active public API key. |
| Please provide an API key pair. |
| Please provide a valid private API key. |
| Please provide a live API key pair when not using the sandbox environment. |
| Please provide an active API key pair. |
| Could not find the resource(s) specified in the request. |