Error Handling

The MerkleMap API uses conventional HTTP response codes and returns detailed error information in JSON format.

Error Response Format

All error responses follow this format:

{
    "status": "ErrorType",
    "message": "A descriptive message about the error"
}

HTTP Status Codes

The API uses standard HTTP status codes to indicate the success or failure of requests:

Name
400 Bad Request
Description
The request was malformed or contained invalid parameters. This includes query parameter validation errors.
Name
401 Unauthorized
Description
No valid API token was provided, the token is invalid or no subscription is active.
Name
404 Not Found
Description
The requested resource doesn't exist.
Name
500 Internal Server Error
Description
Something went wrong on our servers.

Error Types

Name
BadRequest
Description
Indicates that the request parameters were invalid or malformed.
Name
Unauthorized
Description
Authentication failed or wasn't provided.
Name
QueryRejection
Description
The query parameters failed validation.
Name
NotFound
Description
The requested resource was not found.
Name
InternalServerError
Description
An unexpected error occurred on the server.

Example Errors

{
    "status": "BadRequest",
    "message": "Bad request"
}

Error Handling Example

fetch('https://api.merklemap.com/v1/search?query=example.com')
    .then(response => {
        if (!response.ok) {
            return response.json().then(err => {
                throw new Error(`${err.status}: ${err.message}`);
            });
        }
        return response.json();
    })
    .catch(error => {
        console.error('API Error:', error.message);
    });