Skip to content

API error codes

Enterprise feature

The REST API is available on Enterprise plans. Compare plans to find the right fit for your team.

When an API request fails, the response includes an HTTP status code and a structured JSON body with details about the error. This page covers every error you may encounter and how to resolve it.

Error response format

All error responses follow this structure:

{
  "success": false,
  "error": "error_code",
  "message": "A human-readable description of what went wrong."
}
Field Type Description
success boolean Always false for errors
error string Machine-readable error code (snake_case)
message string Human-readable description you can display to users

HTTP status codes

400 — Bad request

The request is malformed or contains invalid data.

Error code Description How to fix
validation_failed One or more required fields are missing or invalid Check the request body against the endpoint documentation
missing_required_field A required field was not included Add the missing field to your request
invalid_status_transition The requested status change is not allowed Check the valid transitions table for the resource
meter_not_found The specified meter does not exist for this asset Configure meters for the asset in the dashboard first

401 — Unauthorized

Authentication failed or was not provided.

Error code Description How to fix
unauthorized API key is missing, invalid, or revoked Verify your X-API-Key header contains a valid key

Check your key

If you recently rotated your key, make sure all integrations use the new one. Revoked keys return 401 immediately.

403 — Forbidden

The API key does not have permission for this action.

Error code Description How to fix
forbidden The key's scopes do not include the required permission Update the key's scopes in Settings → API Keys
ip_not_allowed Request came from an IP not in the key's whitelist Add the source IP to the key's whitelist or remove the restriction
scope_not_authorized The API key lacks the required scope for this operation Add the required scope to your API key in Settings → API Keys

404 — Not found

The requested resource does not exist.

Error code Description How to fix
not_found The resource ID does not exist or is not accessible Verify the ID is correct and belongs to your company

405 — Method not allowed

The HTTP method is not supported for this endpoint.

Error code Description How to fix
method_not_allowed You used the wrong HTTP method (e.g., DELETE on a read-only endpoint) Check the endpoint documentation for the correct method

409 — Conflict

The request conflicts with the current state of the resource.

Error code Description How to fix
duplicate_customer A customer with this email already exists Use the existing record or update it instead

429 — Too many requests

You have exceeded the rate limit.

Error code Description How to fix
rate_limit_exceeded Too many requests in the current time window Wait for the duration specified in the Retry-After header

The response includes a retry_after field (seconds) and a Retry-After HTTP header.

See Rate limits for best practices.

500 — Server error

An unexpected error occurred on the server.

Error code Description How to fix
server_error An internal error occurred Retry the request after a short delay. If the issue persists, contact support.

Troubleshooting checklist

Use this checklist when you encounter an API error:

  • Check the HTTP status code — it tells you the category of the problem.
  • Read the error and message fields — they pinpoint the specific issue.
  • Verify your API key — is it valid, not revoked, and included in the X-API-Key header?
  • Check your scopes — does the key have permission for this operation?
  • Validate your request body — are all required fields present and correctly typed?
  • Review the Retry-After header — if rate-limited, wait before retrying.
  • Contact support — if you see 500 errors consistently, reach out with the request details.

Frequently asked questions

Why do I get 401 even though my key looks correct?

Make sure the key is in the X-API-Key header — not in the URL or request body. Also verify the key has not been revoked.

Can I get more details about a 400 error?

Yes. The message field describes which validation rule failed, and in most cases names the problematic field.

What should I do on a 500 error?

Retry after a short delay (5–10 seconds). If the error persists, contact support with the request method, endpoint, and approximate timestamp.