service_unavailable

HTTP 503Service Unavailable

A transient, retryable condition. Always carries Retry-After.

This never indicates a problem with your request. It means a dependency was briefly unavailable, or the surface is disabled for this org. Every occurrence is safe to retry after the interval given in Retry-After.

Response shape

{
  "type": "https://api-docs.ahoy.ai/rest/v1/errors/service_unavailable",
  "title": "Service Unavailable",
  "status": 503,
  "detail": "The public API is not enabled for this organisation.",
  "code": "service_unavailable",
  "request_id": "req_01J8Z2K9QW3X4Y5Z6A7B8C9D"
}

reason sub-codes

A reason narrows service_unavailable to a specific cause. New values are additive and never require a version bump, so treat an unrecognised reason as the bare service_unavailable.

reason	Meaning
surface_disabled	The public API is switched off for this org.
entitlement_missing	The entitlement check could not confirm access.
config_unavailable	Configuration could not be read.
entitlement_unavailable	The entitlement service could not be reached.
throttle_unavailable	The rate-limit backend was unreachable, so the request failed closed.
exchange_rate_unavailable	A currency sort or filter needed exchange rates that were not available for that day.
upsert_lock_contended	Another write held the upsert lock for this record.
upsert_lock_unavailable	The upsert lock could not be acquired.

How to resolve it

• Retry after the interval in Retry-After, with exponential backoff.
• If reason is surface_disabled, the API is not enabled for your org yet — contact Ahoy support.
• Persistent upsert_lock_contended usually means concurrent writers on the same record; serialise them.