Errors

Crisps uses conventional HTTP status codes. Error responses are JSON with an error message (some also include context fields such as credits_used):

{ "error": "monthly credit quota exceeded", "credits_used": 1000, "credits_limit": 1000 }

Status codes

Status	Meaning	What to do
200 OK	Success.	—
400 Bad Request	Invalid parameters (e.g. malformed body).	Fix the request payload.
401 Unauthorized	Missing, malformed, or revoked API key.	Check the key and the Authorization header.
402 Payment Required	Monthly credit quota exceeded.	Raise your limit or upgrade in the dashboard.
403 Forbidden	The key lacks the required scope, or is limited to basic depth.	Use a key permitted for this endpoint/depth.
429 Too Many Requests	Per-minute rate limit exceeded.	Back off; honour the Retry-After header.
502 Bad Gateway	Upstream search backend failed.	Retry with backoff.

Response headers

Every metered response includes usage headers:

Header	Description
X-RateLimit-Limit	Requests allowed per minute on your plan.
X-RateLimit-Remaining	Requests left in the current window.
X-Credits-Limit	Monthly credit allowance.
X-Credits-Used	Credits used this month (including this call).
X-Credits-Remaining	Credits left this month.
Retry-After	Seconds to wait before retrying (on 429).

Idempotency

Pass an Idempotency-Key header to make a request safe to retry — Crisps de-duplicates repeated calls with the same key within your organization, so a retried request isn’t billed twice.

curl

curl -X POST https://api.crisps.ai/search \
  -H "Authorization: Bearer $CRISPS_API_KEY" \
  -H "Idempotency-Key: 2f9c1a7e-…" \
  -H "Content-Type: application/json" \
  -d '{"query": "…"}'

Python

import os, httpx

httpx.post(
    "https://api.crisps.ai/search",
    headers={
        "Authorization": f"Bearer {os.environ['CRISPS_API_KEY']}",
        "Idempotency-Key": "2f9c1a7e-…",
    },
    json={"query": "…"},
)

Node.js

await fetch("https://api.crisps.ai/search", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CRISPS_API_KEY}`,
    "Idempotency-Key": "2f9c1a7e-…",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ query: "…" }),
});

Recommended retry policy

• Retry 429 and 502 with exponential backoff (e.g. 1s, 2s, 4s, jittered).
• Do not retry 400, 401, 402, or 403 — they need a change on your side.
• Reuse an Idempotency-Key across retries so a succeeded-but-timed-out call isn’t charged twice.