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 CodesMeaning
100sInformational codes indicating that the request initiated by the browser is continuing.
200sSuccess codes returned when browser request was received, understood, and processed by the server.
300sRedirection codes returned when a new resource has been substituted for the requested resource.
400sClient error codes indicating that there was a problem with the request.
500sServer 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 CodesMeaning
403Access 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.

codeintegerRequired. 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.
messagestringRequired. This message is end-user displayable information which may aid in diagnosis and error reporting.
debugMessagestringNot 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.
   "message":"Account not found",
   "debugMessage": "No accounts were found for this customer."

Error codes

HTTP Status CodeFDX Error CodeError MessageDescription
400401Invalid inputInput sent by client does not satisfy API specification.
400702Invalid start or end dateStart or end date value is not in the ISO 8601 format.
400703Invalid date rangeThe start date is not earlier than the end date, or the date range is beyond what the system supports.
401602Customer not authorizedCustomer does not have authorization to perform this action. Please attempt to refresh the token. See the Token guide.
403403Subscription not foundThis 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.
404601Customer not foundCustomer with ID not found. Token may have been revoked.
404701Account not foundAccount with ID not found.
422704Account type not supportedRequest 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.
4291207Too many requestsToo many requests were sent within a short period of time.
500500Internal server errorCatch-all exception for requests that were not processed due to an Akoya-originated outage/issue.
500501Subsystem unavailableCatch-all exception for requests that were not processed due to a Data Provider-originated outage/issue.
503503Scheduled MaintenanceThe system is down for maintenance.

Change log

2024-Apr-15Added error code 503.
2023-Nov-15Added FDX 1207/HTTP 429
2023-Oct-03Updated description for FDX 602/HTTP 401
2023-Sep-06Added recommendation for handling 500-level errors
2023-Apr-26Updated error messages to FDX 5.1
2023-Jan-08Added definition for error 403 - subscription not found
2022-Oct-21Updated description for FDX 704/HTTP 422 error
2022‑Mar‑02Added error 704 to support payment-networks error