Error handling

clock 5-minute read calender 2.4.0 | updated Mar. 13, 2024

Is it you? Is it me? Is it us? Let's figure it out.

An error can indicate a problem with the request, the network, or the API itself. Use the error handling information to get a better understanding of what went wrong and possible corrective actions.

Each error response returns the standard HTTP code number with the exception schema. KeyBank utilized the standard HTTP messaging so nothing too fancy.

Code Status Description
200 OK; Successful The action was successful. No additional actions are needed.
400 Missing mandatory information Request is missing required information.
401 Unauthorized request Invalid credentials for the request.
403 Forbidden request access

You do not have permission to complete the request.

404 Resource not found

The resource for the request cannot be found.

405 Invalid request method The wrong request method was used.
415 Invalid request type

The wrong media type submitted with the request.

429 Request timeout

There are too many requests to the API and a timeout goes into effect.

500 Unknown error

There was an unknown error with the server.

502 Bad gateway

The servers cannot talk to each other or there is a miscommunication.

503 Unavailable service The service is temporarily down.
504 Unable to process request Request needs more time to be processed.



The exception schema includes the error message, your unique X-CorrelationId, and additional information like TransactionId and TransactionTime. The transaction ID and timestamp are helpful in diagnosing the issue. The X-CorrelationId is helpful for transaction traceability and may help determine where did the error occurred.

The exception schema may also contain the ServiceError field for API-specific errors or problems with backend services. This object can contain a few different values, depending on the API or circumstance:

  • connectError - error information of the connectivity with downstream service.
  • detailMessage - an error code with a detailed message.
  • serviceErrorData - API-specific error details about the failed transaction.
  • variable field based on API - custom messages about API-related functional business messages or faults.


Standard error format
  "ErrorMessage": string,
  "X-CorrelationId": string,
  "TransactionId": string,
  "TransactionTime": string,
  "ServiceError": object

Some APIs contain status messages in the responseHeader object of the response payload. Review the status field to see if the transaction was successful (S), was successful but has a warning (W), or failed (F). Additional information is shared in the statusDescription field.

  • S: A successful response. (HTTP 200) 
  • W: The transaction was not not processed as expected. A warning message means the request was successfully received, but there was a minor issue that requires your attention. (HTTP 299)
  • F: The transaction was not processed. (HTTP 400s/500s)

API-specific status messages are explained in depth on the API doc pages where applicable.


Status message example
  "responseHeader": {
     "status": "S",
     "statusDescription": "Successfully returned results for the requested range 1 to 1",
     "retrivedRows": "1",
     "totalRows": "1",
     "dataLoadDate": "2022-07-13"