Skip to main content
All errors return JSON with a consistent structure:
  • errorCode. Machine-readable
  • message. Human-readable explanation

​
Status codes

​
The two 402s

A 402 is always “stop”, but which ceiling stopped you decides what to do next: See Rate Limits & Credit Limits for the monthly ceiling and the headers it reports on.

​
Retry rules

  • Retry only: 429 and 5xx
  • Do not retry: 400, 401, 403, 404, 422
  • Stop on: 402 (either ceiling reached)

​
Backoff strategy

  • On 429 → wait for X-RateLimit-Reset
  • On 5xx → retry with exponential backoff (start ~1s, max 3–5 attempts)

​
Request IDs

Every response — success or error — carries an X-Request-ID header uniquely identifying that request:
When something goes wrong and the message alone doesn’t explain it, include this ID in your report to api-support@tryspecter.com. It lets us trace the exact request through our logs and diagnose the issue on our side.
Send your own X-Request-ID on the request and we echo it back on the response, so you can correlate it with your own logs. If you don’t send one, we generate it for you.

​
Notes

  • 404 = resource doesn’t exist
  • Empty results (200 + []) = valid, but no data
  • 400 and 5xx are not charged
  • Per-result endpoints only charge for data returned