Errors

HTTP Codes

The dfuse API uses the following HTTP error codes:

Error CodeMeaning
400Bad Request – Your request is invalid.
401Unauthorized – Your API key is wrong.
403Forbidden – Your request Origin does not match or while authenticated, you do not have access to specified resource.
404Not Found – The specified resource could not be found.
405Method Not Allowed – You are using an HTTP verb that is not allowed for this resource.
500Internal Server Error – We had a problem with our server. Try again later.
503Service Unavailable – We’re temporarily offline for maintenance. Please try again later.

The HTTP response will always contain a body with a specific error format that is defined in the section below. If the body does not contain anything or is not in the format described below, please report this as a bug to our team.

Error Format

Each error message structure for both the REST API and WebSocket API is fully standardized across all our API calls.

The format is as follows:

{
    "code": "a_unique_error_code_for_this_specific_error",
    "trace_id": "unique_id_identifying_your_request",
    "message": "A descriptive error message about the problem.",
    "details": {
        "key": "contextual key/values pairs specific to each error"
    }
}

Each error returned to you has a unique code field which descriptively identifies the error. The error code is stable in time and can be programmatically relied upon in your code to process the error.

The trace_id uniquely identifies your request, will change upon each request, being unique across all traces. This can be provided to our support team when investigating problems.

The message is a human-readable english string about why the error happened and what went wrong. It may change over time and should not be used to determine what the error was. Use the code field for that purpose.

The details is a key/value pair object and is optional, so it might or might not be present. It contains error-specific details about what went wrong for a given error code. It’s unique per code, and can be used programmatically to extract information about the error.

NameTypeOptionsDescription
codestringrequiredUnique code field which descriptively identifies the error.
trace_idstringrequiredUnique identifier of the request.
messagestringrequiredHuman-readable english string about why the error happen and what was wrong, never translated.
detailsmap<string, any>optionalKey/value pair object contains specific details about what went wrong for a given error code.