Errors, limits, and retries

API clients should make decisions from HTTP status codes, stable error codes, and response headers. Do not hard-code quota values by plan name: Gateway and service limits are driven by the active plan, administrator configuration, profile, and current product policy.

Error envelope

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "message": "The API key does not have the required scope.",
    "status": 403
  }
}

Some proxied services can return a service-specific envelope. Always preserve the HTTP status and response body in structured diagnostic logs, but redact credentials and sensitive user data.

Common statuses

Status	Meaning	Client action
400	Invalid request shape or parameter	Correct the request; do not retry unchanged.
401	Missing, invalid, expired, or revoked credential	Replace or renew the credential.
403	Scope, service, role, plan, quota, IP, or resource policy denied the operation	Inspect the error code and current account configuration.
404	Route or requested resource was not found	Verify the API version, path, identifier, and resource visibility.
409	The operation conflicts with current resource state	Refresh state before deciding whether to retry.
429	A live per-minute or daily request limit was reached	Wait for Retry-After; reduce concurrency or polling.
500	The request reached a service that failed unexpectedly	Retry only if the operation is safe to repeat.
502, 503, 504	A dependency, control, or service was temporarily unavailable	Apply bounded exponential backoff with jitter.

Gateway error codes can include MISSING_API_KEY, INVALID_API_KEY, IP_NOT_ALLOWED, INSUFFICIENT_SCOPE, RATE_LIMIT_EXCEEDED, DAILY_LIMIT_EXCEEDED, RATE_LIMIT_UNAVAILABLE, NOT_FOUND, SERVICE_UNAVAILABLE, and INTERNAL_ERROR. Destination services can return additional codes for their own resources and quotas.

Live limit headers

Successful and rejected authenticated requests can include:

X-RateLimit-Limit: <current minute limit>
X-RateLimit-Remaining: <requests left in the current minute window>
X-RateLimit-Reset: <Unix timestamp>
X-DailyLimit-Limit: <current daily limit>
X-DailyLimit-Remaining: <requests left in the current daily window>
Retry-After: <seconds>

Read these values at runtime. Limits can differ by plan, account, profile, administrator policy, and release stage, and they can change without a client release.

Retry strategy

Use bounded exponential backoff with jitter for transient statuses. A practical sequence begins near one second and grows until a modest maximum delay. Honor a larger Retry-After value when one is present.

Retry only when the operation is safe:

• GET requests are normally safe to retry.
• A failed create, send, or update can have completed before the connection failed. Confirm resource state before repeating it.
• Do not retry 400, 401, or most 403 responses without changing the request or credential.
• Set a maximum attempt count and surface a useful error after it is reached.

Reduce unnecessary traffic

• Cache read-only entitlement or metadata responses for an appropriate short period instead of checking them on every UI interaction.
• Prefer webhooks for supported events.
• Coalesce identical requests from the same workload.
• Paginate large collections and avoid unbounded concurrency.
• Use the CLI’s --json output in scripts instead of issuing duplicate API requests for formatting.

Diagnose an unexpected denial

1. Call GET /v1/auth/whoami to confirm the active identity and key.
2. Call GET /v1/auth/quota for the current Gateway quota snapshot.
3. Confirm the key has the route’s required scope.
4. Confirm the destination service is enabled for the active profile.
5. Check role and organization permissions in the destination service.
6. Record the status, error code, response headers, and request time before contacting CHAMPREP Support.