Errors

While using the Climatiq API, you might encounter errors due to various reasons. In such cases, the API returns an appropriate HTTP status code along with a JSON object containing detailed error information.

You should always check the returned HTTP status code to determine if an error has occurred. If an error is present, examine the provided error object for more details.

Status Codes

This is a list of the common HTTP status codes the Climatiq API returns.

200 OK: Everything worked as expected.
400 Bad Request: The request was unacceptable, probably due to missing a required parameter.
401 Unauthorized: No valid API key was provided.
403 Forbidden: An API key was provided, but it was not valid for the operation you tried to attempt.
404 Not Found: The requested resource doesn't exist.
429 Too Many Requests: You have performed too many requests recently.
500 Internal Server Error: Something went wrong on our end. Please try again a bit later.
503 Service Unavailable: We're temporarily having trouble providing this service. Please inspect the Retry-After Header (opens in a new tab) for an appropriate time to retry this request.

Error JSON Structure

If an error occurs, the API returns a JSON object with the following fields:

Attribute
error string A string representing the HTTP status code returned.
error_code string or null A string providing a more specific error code for certain types of errors. This is primarily provided in cases where we deem it likely that you are able to handle the error programmatically.
message string A human-readable description of the error.

The error response might also include additional fields to help you understand the error better, such as valid choices for specific parameters.

{
    "error": "bad_request",
    "error_code": "invalid_unit_type_supplied",
    "message": "Unable to find any emission factors compatible with the Unit Type provided. This error will contain a list of valid units for this selection.",
    "valid_values": {
        "unit_type": ["Number"]
    }
}

Error Codes

The API returns error codes for situations where you might want to act programmatically on the returned errors, such as prompting an end-user to provide different input, or rate-limiting your API calls. These error codes depend on the HTTP status code returned. The error codes listed here are not exhaustive and more may be added over time.

400 Error Codes (Bad Request)

These error codes are returned when the HTTP status code is 400, indicating that your request is invalid for some reason. You will need to modify the request before trying again.

Error Code	Description
`invalid_unit_type_supplied`	The provided unit type did not match any units of found emission factors. Provide a different unit or select a different emission factor.
`invalid_input`	The user input does not allow the API call to be completed. This is a generic error code for when more specific ones are not appropriate.
`batch_limit_exceeded`	For a batch endpoint, you attempted to batch too many operations at once. Reduce the number of batch operations in one request.
`no_route_found`	We could not find a route between two of the provided locations.
`no_emission_factors_found`	A query resulted in no valid emission factors being found. Modify your selector.
`no_location_found`	We were unable to find a given location or country with the provided information, or the location was not of the expected type.
`no_matching_resource_found`	The resource you tried to access, use, or modify did not exist, or you might not have permission to access it.
`functionality_unsupported`	The given functionality is currently not supported. If you encounter this error and need the functionality, please reach out to us.

429 Error Codes (Too Many Requests)

These error codes are returned when the HTTP status code is 429, indicating that you have performed too many requests. You will need to wait before sending another request.

Error Code	Description
`quota_exceeded`	The quota for your project has been exceeded. Please try again next month or upgrade your plan.
`temporarily_rate_limited`	You have made too many requests and are temporarily rate-limited. Please try again in a few minutes. Currently Climatiq does not perform rate-limiting of your calls, but we might do so in the future.

Batch Endpoint Errors

Normally, the error codes listed above correspond to HTTP status codes. However, this is not the case for batch endpoints where some operations in the batch might fail independently of each other. This means you might receive an error code that indicates a "Bad Request" for one part of your batch operation, even though the overall request returns a 200 status code.

When handling batch endpoint errors, it is essential to inspect the error information for each individual operation in the batch and take appropriate action accordingly.

Batch Endpoints Search