API errors

Expected API errors return JSON with an error.code and error.message. They also include an X-Request-Id header for support and debug correlation.

{
  "error": {
    "code": "validation_error",
    "message": "Invalid search request"
  }
}

Use error.code for application logic. Messages may change.

Error codes

HTTP status	Code	Meaning	Fix
`401`	`missing_api_key`	Missing or malformed `Authorization: Bearer <api-key>` header.	Set `REPOSEEK_API_KEY` or send the Bearer header.
`401`	`invalid_api_key`	Key is unknown, revoked, inactive, or the account cannot use it.	Create or regenerate a key in the dashboard.
`422`	`validation_error`	Request JSON or search body is invalid.	Check `query`, `limit`, JSON syntax, and unknown fields.
`429`	`rate_limit_exceeded`	Too many requests in the current rate window.	Retry later or reduce request rate.
`429`	`quota_exceeded`	Search quota is exhausted for the current quota window. The payload includes usage metadata when available.	Wait for reset, upgrade, or manage billing.
`503`	`embedding_unavailable`	Embedding provider is temporarily unavailable.	Retry later.
`503`	`reranker_unavailable`	Reranking provider is temporarily unavailable.	Retry later.

Quota errors may include:

{
  "error": {
    "code": "quota_exceeded",
    "message": "You've used your 10 free searches for this month. Upgrade to Pro for 100 searches/month. Same search quality, higher monthly volume.",
    "usage": {
      "remaining_searches": 0,
      "next_reset_at": "2026-06-01T12:00:00+00:00"
    }
  }
}

Unexpected server errors may return a simpler server-error body. Treat any 5xx as retryable with backoff unless your application has stronger context.