The ekko Climate API uses a unified error format across all endpoints. Every error response has the same structure, making it straightforward to handle errors programmatically.

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

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.