Error handling | API Documentation

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.

HTTP status codes

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.

Standard error message format

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
}

Response header status messages

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"
     },
}