Akoya uses HTTP status and error codes to indicate the success or failure of a request. For status codes other than 200, the HTTP response body will contain an error entity.
| HTTP Status Codes | Meaning |
|---|---|
| 100s | Informational codes indicating that the request initiated by the browser is continuing. |
| 200s | Success codes returned when browser request was received, understood, and processed by the server. |
| 300s | Redirection codes returned when a new resource has been substituted for the requested resource. |
| 400s | Client error codes indicating that there was a problem with the request. |
| 500s | Server error codes indicating that the request was accepted, but that an error on the server prevented the fulfillment of the request. We recommend implementing three (3) retries to help your app deal with short-lived, transient failures. The waiting time between retries should increase exponentially with each retry attempt. |
Specific HTTP status and error codes may include:
| HTTP Status Codes | Meaning |
|---|---|
| 403 | Access if forbidden. This may mean the route is incorrect. For example, if the version number is wrong. |
Error body
Akoya data APIs support the ability to include debugging information with errors as defined in FDX 5.1 (RFC 01870). The debugMessage is not always present but will be included when possible.
FDX exception
Akoya error codes are consistent with FDX API 5.1 standards with the following exception:
The error code is returned as an integer rather than a string.
| element | type | description |
|---|---|---|
| code | integer | Required. Akoya returns the error code as an integer rather than a string (as specified by FDX). The code is a long term persistent identifier which can be used to trace error conditions back to log information. |
| message | string | Required. This message is end-user displayable information which may aid in diagnosis and error reporting. |
| debugMessage | string | Not required. Message used to debug the root cause of the error. Contents should not be used in business logic. These messages may change at any time and should only be used for troubleshooting an issue. |
{
"code":701,
"message":"Account not found",
"debugMessage": "No accounts were found for this customer."
}
Error codes
| HTTP Status Code | FDX Error Code | Error Message | Description |
|---|---|---|---|
| 400 | 401 | Invalid input | Input sent by client does not satisfy API specification. |
| 400 | 702 | Invalid start or end date | Start or end date value is not in the ISO 8601 format. |
| 400 | 703 | Invalid date range | The start date is not earlier than the end date, or the date range is beyond what the system supports. |
| 401 | 602 | Customer not authorized | Customer does not have authorization to perform this action. Please attempt to refresh the token. See the Token guide. |
| 403 | 403 | Subscription not found | This error may be caused any of the following: 1. The providerId in your request is incorrect. 2. Your app isn’t subscribed to the requested provider. 3. Your app isn’t subscribed to the requested Akoya product. Please check the Akoya Hub to determine your subscription details. |
| 404 | 601 | Customer not found | Customer with ID not found. |
| 404 | 701 | Account not found | Account with ID not found. |
| 408 | Request timeout | Request timed out (round trip call took >10 seconds). | |
| 422 | 704 | Account type not supported | Request made for investment, loans, taxes, statements and other functions that we currently do not support. Error also covers certain account types that are not supported, such as if an account doesn’t support payment-networks. |
| 429 | 1207 | Too many requests | Too many requests were sent within a short period of time. |
| 500 | 500 | Internal server error | Catch-all exception for requests that were not processed due to an Akoya-originated outage/issue. |
| 500 | 501 | Subsystem unavailable | Catch-all exception for requests that were not processed due to a Data Provider-originated outage/issue. |
| 503 | 503 | Scheduled Maintenance | The system is down for maintenance. |
Change log
| Date | Update |
|---|---|
| 2025-Feb-27 | Updated FDX error code 601; added error code 408. |
| 2024-Aug-06 | Added dev help resources. |
| 2024-Apr-15 | Added error code 503. |
| 2023-Nov-15 | Added FDX 1207/HTTP 429 |
| 2023-Oct-03 | Updated description for FDX 602/HTTP 401 |
| 2023-Sep-06 | Added recommendation for handling 500-level errors |
| 2023-Apr-26 | Updated error messages to FDX 5.1 |
| 2023-Jan-08 | Added definition for error 403 - subscription not found |
| 2022-Oct-21 | Updated description for FDX 704/HTTP 422 error |
| 2022‑Mar‑02 | Added error 704 to support payment-networks error |
Need help?
Check out our Developer Community, or visit the Support Center in the Data Recipient Hub.
Looking for provider nuance documentation?
All provider nuance documentation is available in the Data providers section in the Data Recipient Hub.
Still stuck?
For all production issues, submit a support ticket through the Data Recipient Hub. Our support team is standing by 24/7. Questions and non-production issues will be answered during business hours.