Error handling

clock 2-minute read calender updated Sep. 25, 2025

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.

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

When you get an error response, look at these key items to help diagnose the issue.

1.

Look at the HTTP status code

What is the HTTP status code? This number will help you identify if the problem is on your side (4xx error codes) or our side (5xx error codes).

  • If it an error in the 400s, the problem is likely on your side. This means you either need to check the request data, verify your connection or permissions.
  • If it is an error in the 500s, the problem is on us. There is an issue with the backend services.

2.

Review the error message

If you received a error response, get familiar with the error format. Look at what the error message for details. If the message is hard to decipher, go to our troubleshooting to better understand what this error means, possible reasons it occurred, and how to resolve.

3.

Check other details

Additional information may also be in header status message or in a service error depending on the API. Service errors contain specific error messages from the API service. This will give you additional details you will need to resolve the issue or information to assist our support teams if escalation is required.

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. 

If you need help resolving an error, review our troubleshooting to see if you can resolve any errors prior to escalating to KeyBank support.

CodeStatusDescription
200OK; SuccessfulThe action was successful. No additional actions are needed.
400Bad Request; Missing mandatory informationRequest is invalid or 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.

 

We use the exception schema to share information about any errors encountered, either with permissions, the network, or backend services. 

Standard errors

Each error response includes the header information to help diagnose the reason for the error. If you receive a HTTP 400s or HTTP 500s error, the standard response header contains the following:

  • ErrorMessage is the standard system message associated with the HTTP status code.
  • X-CorrelationId is the system-generated unique ID associated with your request upon submission.
  • TransactionId is the API-generated unique ID for the transaction.
  • TransactionTime is the date and time of generated error response. Since KeyBank is an eastern-based financial institution, the timestamp is for the EST time zone.

Service errors

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. Some typical fields in the ServiceError object are:

  • 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.

Refer to the API documentation to view more information about any specific messages about API-related functional business messages or faults.

Error example

{
  "ErrorMessage": "System-generated error message",
  "X-CorrelationId": "2ebd5c24-0e8d-5a70-0e91-ffd2727c1aab",
  "TransactionId": "a1054ca9-2e48-491d-adda-8eb51cceb9c6",
  "TransactionTime": "2025-06-12T16:31:34.041Z",
  "Api-Url": "{hostname}/path/endpoint",
  "ServiceError": {
    "connectError": "Service error code",
    "detailMessage": "Service error description from API",
    "serviceErrorData": "Additional data about the service error occurrence"
    }
}

Sometimes it's okay to get ahead of yourself. There are a few API response payloads that include a status message in the responseHeader object. This is an extra way to keep a pulse on the health of your request and the data you are sending or retrieving.

  • Status and details let you know 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)
  • Data details about how much data was retrieved, the date the data was collected, and possible pagination information.

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

Status example

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