Specter API Error Codes, Rate Limits, and Retry Guidance

When a Specter API request fails, the response uses a standard HTTP status and a JSON body containing a machine-readable error code. Use the code, not the message text, to decide how to handle the failure.

Error format

{
  "error": {
    "code": "insufficient_scope"
  }
}

Error codes

Status	Code	Meaning	Retry?
`400`	`invalid_request`	A parameter or credential is malformed, missing, or duplicated.	No. Fix the request.
`400`	`report_too_large`	The alert summary range exceeds its limits.	No. Narrow the date range or use a coarser granularity.
`401`	`invalid_api_key`	The API key is missing, invalid, expired, or revoked.	No. Use a valid key.
`403`	`insufficient_scope`	The key belongs to another organization or lacks the required permission.	No. Grant the permission.
`429`	`rate_limited`	The per-key admission limit or the organization’s operation quota is exhausted.	Yes, after `Retry-After`.
`503`	`api_unavailable`	A dependency failed.	Yes, with backoff.
`503`	`server_overloaded`	Global admission or concurrency limits are exhausted.	Yes, after `Retry-After`.
`504`	`deadline_exceeded`	The operation deadline elapsed before it completed.	Yes, with backoff.

Retrying requests

Check the status code

Only retry 429, 503, and 504 responses. Other errors need a change to the request or key.

Honor Retry-After

When the response includes a Retry-After header, wait at least that many seconds before trying again.

Back off exponentially

If there is no Retry-After header, wait progressively longer between attempts and cap the total number of retries.

Successful responses from GET /api/v1/platform-health include an X-Request-Id header. Log it so you can reference specific requests when you contact support.

​Error format

​Error codes

​Retrying requests

Error format

Error codes

Retrying requests