Error handling

clock 5-minute read calender Rel. 4.0.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.

CodeStatusDescription
200OK; SuccessfulThe action was successful. No additional actions are needed.
400Missing mandatory informationRequest is missing required information.
401Unauthorized requestInvalid credentials for the request.
403Forbidden request accessYou do not have permission to complete the request.
404Resource not foundThe resource for the request cannot be found.
405Invalid request methodThe wrong request method was used.
415Invalid request typeThe wrong media type submitted with the request.
429Request timeoutThere are too many requests to the API and a timeout goes into effect.
500Unknown errorThere was an unknown error with the server.
502Bad gatewayThe servers cannot talk to each other or there is a miscommunication.
503Unavailable serviceThe service is temporarily down.
504Unable to process requestRequest 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"
     },
}