> ## Documentation Index
> Fetch the complete documentation index at: https://api.specter.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Specter API Error Codes, Rate Limits, and Retry Guidance

> Reference for Specter API error responses: HTTP status codes, error code values, Retry-After behavior, and when to retry a failed request safely.

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

```json theme={null}
{
  "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

<Steps>
  <Step title="Check the status code">
    Only retry `429`, `503`, and `504` responses. Other errors need a change to the request or key.
  </Step>

  <Step title="Honor Retry-After">
    When the response includes a `Retry-After` header, wait at least that many seconds before trying again.
  </Step>

  <Step title="Back off exponentially">
    If there is no `Retry-After` header, wait progressively longer between attempts and cap the total number of retries.
  </Step>
</Steps>

<Tip>
  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.
</Tip>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.