Ask us anything. We're here to help.

API error handling

Periodically, our API is subject to return 4xx or 5xx level error messages. 

 

5xx level errors

These types of errors can occur for various reasons and not all of them indicate an error on the Zero Hash side. Generally, it is good practice to retry your request on any of the following errors:

  • 502 Bad Gateway
  • 503 Service Unavailable
  • 504 Gateway Timeout
  • TCP / socket timeouts

You may want to wait a short time (eg: 100-500ms) before retrying, typically with a linear or exponential backoff. If you fail after 3-5 consecutive times, then you can consider that an error and contact us. Zero Hash will investigate right away. 

In addition, we recommend that clients update their systems to code log the retries and timeouts.

 

4xx level errors

The API can return 4xx level errors in instances, typically due to malformed or unexpected data in the API request. These types of errors can commonly be resolved by reviewing and updating the request. 

 

We summarized the common error status codes returned by our API along with remediation steps below. 

 

Status Code

Type

Description

Remediation Steps

400

Bad Request

The server could not understand the request, most likely due to invalid syntax.

Please check and validate the request is formatted correctly, and reach out to Zero Hash if any further issues. 

401

Unauthorized

The server could not authenticate your request.

Ensure your API keys and request url are valid.

403

Forbidden

You are not authorized to access the requested resource. 

Ensure your API keys and credentials are valid. Also, please check if the resource you're trying to access belongs to your platform.

404

Not Found

The requested resource was not found. 

Please check and validate your request URL and identifiers. 

409

Conflict

The request could not be completed due to a conflict with the current state. This often means you are trying to create a duplicate entity or a failure in acquiring a lock. 

Please check and validate your request. Contact Zero Hash if you continue to experience issues. 

429

Too Many Requests

Too many requests have been sent in a given amount of time.

Retry your request after waiting a given amount of time. 

500

Internal Server Error

The server has encountered an internal error. 

Please capture the details of your problematic request and contact Zero Hash for further troubleshooting.

502

Bad Gateway

There was a glitch in our internal infrastructure. 

Please retry your request using a backoff algorithm and contact Zero Hash if subsequent request attempts continue to fail.

503

Service Unavailable

The server has encountered a transient internal error. It could also mean it failed to acquire an internal lock (in that case, it's not an error, just a race condition)

Please retry your request using a backoff algorithm and contact Zero Hash if subsequent request attempts continue to fail.

504

Gateway Timeout

There was a glitch in our internal infrastructure.

Please retry your request using a backoff algorithm and contact Zero Hash if subsequent request attempts continue to fail.