Troubleshooting

You may not have the correct value specified in your request header or may need to define the header in your request.

When you get this error, it means the payload format that was sent as part of the HTTP request does not match the encoding format specified in the header.

Headers to check

• The Content-Type header defines the media type sent over HTTP. Valid values include application/json, application/xml, or application/x-www-form-urlencoded.
• The Content-Encoding header defines how to modify the content before it is sent. Content encoding compresses content without removing any information about the original media type. Valid values include gzip or deflate.

How to resolve

1. Verify that your request header Content-Type is correct.
2. Resubmit the request.
3. If the same error is received, add the header to the request and choose one of these compression values: gzip or deflate.

Compression types

• gzip: Adds a 32-bit CRC (Cyclic Redundancy Check) to help detect errors during transfer. This is the original method used by the UNIX gzip program.
• deflate: Combines the LZ77 algorithm with Huffman coding, which further reduces file size by sorting data according to how often it appears. This format is packaged inside a zlib structure.

Note: All options use a form of LZ77, a basic algorithm for compression that finds and replaces repeated patterns in data with references to where those patterns first appeared. This makes files smaller and faster to transfer or store.

If you’re unsure which to choose, reach out using out client support form. We’ll reach out with suggestions on the best compression type for your data.

A header appears more than once, with the same or different values, in the HTTP request.

How to resolve

1. Submit a request with our client support form (/support) and request that the support team review the logs. The team or your Technical Account Manager will respond with which header(s) are triggering a message about duplicates.
2. Correct the headers and resubmit the request.

This typically occurs when something isn’t right with your certificate, like one of these reasons:

• The certificate expired.
• KeyBank does not have the correct or current certificate.
• Missing the client root certificate in your trust store.
• Certificate does not load correctly because of import method, certificate store settings, or browser settings.

How to resolve

Certificates can be complicated, so let us help you. Contact us to verify the health of your certificate and help establish a secure handshake between partners.

The access token in the request is either missing or not in the correct field.

How to resolve

1. Review your request headers. Make sure that the correct access token is defined in the Authorization field.
2. Correct and resubmit your request.
3. If you get the error again, you may need to generate a new token.

The access token in the request has expired.

How to resolve

You need to generate a new access token and re-submit the request with the new token. See access token documentation for the basic cURL command.

You do not have permission to access a request. There are possible reasons why you have been denied access:

• You do not have access to this API product.
• There is an issue with the certificate. A certificate issue could be that the certificate was not passed, it has expired, it is not properly signed, or KeyBank does not have the correct certificate installed.

How to resolve

1. Review your access token or send a new request to view the list of resources you have permission to access in the api_product_list field. If the API product is not listed and you would like access to this resource, reach out to your Technical Account Manager.
2. Verify that your certificate configuration is correct. View our certificate requirements in the Get Started Guide or in our FAQs. If it looks like all conditions are being met, reach out to your Technical Account Manager or use the client support form.

The hostname and path of the API URL do not match the API proxy, or the proxy is not associated with the virtual host.

How to resolve

Make sure you are using the correct host and proxy names. If everything looks correct on your end, escalate using our client support form.

It seems like the API URL may not be correct, or the URL path does match any of the resources configured to this proxy.

How to resolve

1. Look at the Api-Url field in error response. Verify that that API URL is valid and matches the path in the API specification.
2. If it is not correct, fix the path and resubmit the request.
3. If you continue to encounter this error, please use the client support form to escalate the issue.

It has to be not only what you say, but how you say it. The HTTP method used for the request is not correct.

How to resolve

With KeyBank API products, the method of the API call will be either GET or POST. Check the API specifications to make sure you are using the correct method. In simple terms, the GET method is to get data and the POST method is to send data.

You may not have the correct request headers or are missing a header value. The Content-Type or Accept should be in part of your request headers. You may also need to define the Content-Encoding header in your request.

How to resolve

1. Verify that your request header fields are correct based on the API specifications. Common headers include:
   • The Content-Type header defines the media type sent over HTTP. Valid values include application/json, application/xml, application/x-www-form-urlencoded. With REST APIs, the payload format is JSON. Try the value application/json.
   • The Content-Encoding header defines how to modify the content before it is sent. Content encoding compresses content without removing any information about the original media type. Valid values include: gzip, deflate.
   • The Accept header specifies the type of content you can receive. Typically, with REST APIs, the accept format is application/json.
2. Correct headers and resubmit the request.
3. If the same error is received, escalate to support for help with the the client support form.

The request has exceeded the rate limit. Going beyond the rate limit is being triggered by the number of connections your app is making to the API or a severe traffic spike affecting performance.

How to resolve

Submit a support form to verify that the limit threshold is causing the error. If so, work with your Technical Account Manager to find a solution or assess if a rate limit change is necessary. For most APIs, the rate limit is set to 5 TPS (read more about Rate limiting).

Your application credentials are not correct in your request header, in particular the consumer_key.

How to resolve

Contact Support with the credentials you are using in the Authorization header. Support will verify and provide the correct credentials.

When you sent the request, the Authorization header was missing. This field is required and acts as a passport to access and use the API product.

How to resolve

Resubmit the request with the Authorization header defined (see Access controls. If you resubmit with the Authorization header complete and still receive this error, escalate to the the client support form.

There is a field value in your request that is using characters that are not allowed or do not conform to the required format.

How to resolve

1. Verify the API URL to make sure there are no erroneous characters in the path.
2. Make sure the parameters being sent match the requirements and conditions specified in the API specifications .
3. If the request looks correct and accurate, escalate with the client support form to get further investigation.

When the request was sent, an error occurred with the secure SSL/TLS connections or there was a backend server timeout.

How to resolve

Reach out to support using the the client support form. The team will check the logs to verify that the backend service was available and if there is a pattern of timeouts for a particular API service. This is an error that must be corrected by KeyBank.

You cannot connect to our API services because a backend service is unavailable, the target endpoint may not be enabled, or the host alias is not correctly configured.

How to resolve

1. Perform the health check to confirm the service is unavailable.
2. If the service is unavailable, use the client support form to report an outage or contact your Technical Account Manager directly. A service outage is a high priority issue that KeyBank aims to resolve quickly.

This is on us. The backend service is taking too long to respond.

How to resolve

Check to see if there is a notification on the portal. If you see a red banner confirming an outage, please wait until the issue is resolved. If there is no communication on our developer portal, contact your Technical Account Manager immediately. This is a high priority concern that should be address immediately.