Error catalog

Compass returns RFC 7807 problem objects for the v1 decision endpoints, with some auth and legacy routes still returning compact JSON errors.

Authentication

Send your key from signup in X-Compass-API-Key. Sandbox keys use the cmp_test_ prefix and paid keys use the cmp_live_ prefix. The server also accepts Authorization: Bearer as a fallback, but docs examples use the OpenAPI header format.

RFC 7807 problem types

Problem type URLs use the canonical in-site docs path:https://compassfoodtechnologies.com/docs/errors/<error-name>. Each slug below has a dedicated page.

Field	Type	Notes
invalid-request	400	Request body or X-Compass-Mode failed validation.
restaurant-not-found	404	The submitted compass_id does not resolve to an active restaurant.
upstream-unavailable	503	Embedding service or vector search was unavailable.
internal-error	500	The request could not be completed because of a server error.

Auth, quota, and access errors

Field	Type	Notes
missing_api_key	401	No Compass API key was supplied.
invalid_api_key	401	The supplied key format or key record is invalid.
key_suspended	403	The key was suspended.
key_revoked	403	The key was revoked.
key_inactive	403	The key is not active.
key_expired	403	The key has expired.
origin_not_allowed	403	The request origin is not allowed for the key.
ip_not_allowed	403	The request IP is not allowed for the key.
ip_not_in_allowlist	403	The IP allowlist rejected the request.
rate_limit_exceeded	429	Per-minute key rate limit exceeded.
monthly_limit_exceeded	429	Monthly quota exceeded.
ip_rate_limit_exceeded	429	Per-IP rate limit exceeded.
tier_insufficient	403	The endpoint requires a higher tier. Search, Enrich, Decide, and Changes are available on every tier.

Supporting route errors

Field	Type	Notes
not_found	404	Legacy or unsupported endpoint path.
invalid_id	400	Invalid restaurant identifier.
invalid_parameter	400	Invalid query parameter.
invalid_parameters	400	Invalid query parameter set.
missing_parameter	400	Required query parameter missing.
missing_coordinates	400	Required latitude or longitude missing.
radius_too_large	400	Requested radius exceeds the route limit.
page_size_too_large	400	Requested page size exceeds the route limit.
since_too_old	400	Changes cursor is older than the supported window.
daily_refresh_limit	429	Retired with the Refresh endpoint, which now returns HTTP 410 endpoint_gone.
endpoint_gone	410	Retired route. GET /v1/search callers use POST /v1/search. POST /v1/refresh/{compass_place_id} has no replacement.
enterprise_only	403	Retired for Search, Enrich, Decide, and Changes. Those routes are available on every tier.
service_unavailable	503	Route dependency is unavailable.