Errors - Heyrafiki

Every API error returns the same envelope.

{
  "error": {
    "code": "api_key_invalid",
    "message": "This key is not authorized for the Heyrafiki API. Check that you are using the key for this environment.",
    "docs": "https://docs.heyrafiki.space/errors"
  }
}

Branch on error.code. It is stable. The message may change.

Status codes

Status	Meaning	Retry
`200`	Success	No
`400`	Request validation failed	Fix the request
`401`	Key missing, invalid or for another environment	Fix the key
`403`	Key is valid but lacks access	No
`404`	Resource not found or not visible	No
`429`	Rate limit exceeded	After `Retry-After`
`503`	Service temporarily unavailable	After `Retry-After`

Error codes

Code	Status	Cause
`api_key_missing`	401	No `Authorization` or `x-api-key` header
`api_key_invalid`	401	Unknown, revoked, malformed or wrong-environment key
`permission_denied`	403	Key lacks the required scope or resource access
`resource_not_found`	404	Resource does not exist or is not visible to the project
`validation_failed`	400	A request parameter failed validation
`rate_limit_exceeded`	429	The key exceeded its current request limit
`service_unavailable`	503	A required service could not complete the request

Authentication failures

401 responses include WWW-Authenticate.

WWW-Authenticate: Bearer realm="Heyrafiki API", error="invalid_request"

invalid_request means no key was sent. invalid_token means a key was sent and rejected.

Retries

Retry 429 and 503 responses only. Read Retry-After, then use exponential backoff with jitter.

Last modified on August 14, 2026

Related topics

Retrieve a Webhook endpoint Disable a Webhook endpoint Retrieve a Practitioner Send a test event Retrieve a Booking Retrieve a Session