Rate Limits & Error Codes

Rate Limits

A request can hit more than one limit. When any limit is exceeded the API responds with 429 Too Many Requests.

Mechanism	Limit	Window	Scope
General limit	100 requests	1 minute	All authenticated routes, per account or organization
Citations quota	50 requests	1 hour	`POST /citations/activate` and `POST /citations/disable`
Location edit quota	200 requests	1 hour	`PATCH /location/update`
Posts quota	100 requests	1 hour	`POST /post`, `PATCH /post/{id}`, and `DELETE /post/{id}`

Hourly quotas return { "success": false, "msg": "QUOTA_REACHED" }. The general limit also sets rate-limit headers.

Returned on the general limit:

Header	Description
`X-RateLimit-Limit`	Maximum requests in the current window
`X-RateLimit-Remaining`	Requests remaining in the current window
`X-RateLimit-Reset`	UNIX timestamp in milliseconds when the window resets
`Retry-After`	Seconds to wait before retrying

Prefer the Retry-After header when you receive a 429.

Status	Name	Description
200	OK	Request succeeded. Some routes return `{ "success": false, ... }` without changing the status code.
202	Accepted	Request accepted and processing. Poll the resource until a terminal state.
302	Found	OAuth callback redirect. On error, redirects with `?error=<message>`.
400	Bad Request	Invalid or missing parameters, or a business rule violation.
401	Unauthorized	Missing or invalid token, expired token, or account suspended.
403	Forbidden	Token does not have the required authorization level, or a restricted API is not enabled.
404	Not Found	Resource does not exist.
409	Conflict	Resource already in the target state, or a conflicting operation is in progress.
410	Gone	Resource existed but is no longer available (for example a deleted review).
429	Too Many Requests	Quota exceeded.
500	Internal Server Error	Unexpected server-side failure or upstream error.

Most non-200 responses include a code or msg field. Prefer code when present.

{
  "success": false,
  "code": "ALREADY_ACTIVE",
  "message": "Citations are already active for this location"
}

Code	Status	Description
`ALREADY_ACTIVE`	409	Citations are already active for this location.
`NOT_ACTIVE`	409	Citations are not active — cannot disable.
`IN_PROGRESS`	409	A citations operation is already in progress for this location.
`QUOTA_REACHED`	429	Hourly quota exceeded (citations, location updates, or posts).
`MISSING_LOCATION_FIELDS`	400	Required location fields are missing — the response includes `missing_fields`.

New error codes may be added. Treat unknown codes defensively and fall back to the HTTP status.