Errors

Every 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://heyrafiki.space/solutions/developers"
  }
}

Branch on error.code. It is stable. error.message is written for humans and may change.

Status codes

Status	Meaning	Retry
`200`	Success	—
`400`	Request is malformed or fails validation	No, fix the request
`401`	Key missing, invalid, or wrong environment	No, fix the key
`403`	Key is valid but not permitted, or Consent does not allow it	No
`404`	Resource does not exist, or is not visible to this key	No
`409`	Conflict with the resource’s current state	No
`422`	Well-formed but not actionable, such as booking a past Session	No
`429`	Rate limited	Yes, after `Retry-After`
`5xx`	Fault on our side	Yes, with exponential backoff

Error codes

Code	Status	Cause
`api_key_missing`	401	No `Authorization` or `x-api-key` header
`api_key_invalid`	401	Unknown, revoked, or wrong-environment key
`permission_denied`	403	Key lacks the scope for this resource
`consent_required`	403	The Person has not consented to this sharing
`resource_not_found`	404	No such resource for this key
`validation_failed`	400	One or more fields failed validation
`rate_limited`	429	Too many requests

Auth failures

401 responses also carry a WWW-Authenticate header.

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

error="invalid_request" means no key was presented. error="invalid_token" means a key was presented and rejected.

Retries

Retry 429 and 5xx only. Back off exponentially and cap attempts. Write requests accept an Idempotency-Key header, so a retry never creates a second Session, Claim or Payment.

curl https://api.heyrafiki.space/v1/sessions \
  -H "Authorization: Bearer sk_test_xxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: 8f14e45f-ea2b-4c1f-9b23-7a0c2d1e5f60" \
  -d practitioner_id=prc_9a1 \
  -d starts_at=2026-08-04T10:00:00Z

Get started

API reference

Platform

Changelog

Status codes

Error codes

Auth failures

Retries

​Status codes

​Error codes

​Auth failures

​Retries

Status codes

Error codes

Auth failures

Retries