The ekko Climate API uses a unified error format across all endpoints. Every error response has the same structure, so a single handler covers every endpoint.

Error format

All errors follow this structure:

{
  "error": "descriptive error message",
  "code": "ERROR_CODE"
}

The error field contains a human-readable description of what went wrong. All error messages are lowercase for consistency and machine-readability.

The code field is derived from the HTTP status code. In some cases, a more specific domain code is returned instead.

Status codes

HTTP status	Code	Description
`400`	`BAD_REQUEST`	Missing or incorrect parameters
`401`	`UNAUTHORIZED`	Invalid or missing API key
`403`	`FORBIDDEN`	The API key doesn't have permission for this request
`404`	`NOT_FOUND`	Resource not found
`409`	`CONFLICT`	The request conflicts with the current state of a resource
`413`	`REQUEST_ENTITY_TOO_LARGE`	The request payload exceeds the allowed size
`422`	`UNPROCESSABLE_ENTITY`	The request is well-formed but contains invalid data
`500`	`INTERNAL_SERVER_ERROR`	An unexpected error on ekko's side
`503`	`SERVICE_UNAVAILABLE`	A dependency was unreachable, so the request was not performed

📘
Checking for a service issue
If you see repeated 500 or 503 responses, check the ekko status page for current API availability and open incidents.

Domain-specific codes

Some errors return a more granular code when additional context is available. For example, a 409 response might return a domain-specific code like MAX_KEYS_REACHED instead of CONFLICT to indicate the exact reason for the conflict.

Domain-specific codes always correspond to the same HTTP status code as their parent. When you receive one, you can handle it more precisely than the generic code allows.

Idempotency codes

Requests that carry an Idempotency-Key header can return these codes. See Idempotency for which of them are safe to retry.

HTTP status	Code	Description
`400`	`IDEMPOTENCY_KEY_INVALID`	The key is over 255 characters or contains characters outside printable ASCII
`409`	`IDEMPOTENCY_KEY_IN_FLIGHT`	The first request with this key is still running
`409`	`IDEMPOTENCY_RESOURCE_GONE`	The resource the key created has since been reversed or deleted
`422`	`IDEMPOTENCY_KEY_REUSED`	The key was used with a different request body

Versioning codes

Requests can return these codes when the Ekko-Version header is missing or isn't a released version. See Versioning.

HTTP status	Code	Description
`400`	`API_VERSION_INVALID`	The header isn't a released version, either because it isn't shaped like `YYYY-MM-DD.animal` or because no such version exists
`400`	`API_VERSION_REQUIRED`	The request has no `Ekko-Version` header