Opsis API / v1
Errors & rate limits
Handle errors, back off safely, and avoid duplicate searches.
Handle HTTP errors
Inspect both the HTTP status and response body. Errors may use a top-level error / message, a detail object or string, or a validation-error array.
| Status | What to do |
|---|---|
| 400 / 422 | Validate the request type, required fields, and query format. Fix the request before retrying. |
| 401 | Check the authentication header. The key may be missing, invalid, or revoked. |
| 402 | insufficient_api_credits or api_credit_adjustment_required. Top up or review subscription fallback. |
| 403 | Review plan eligibility. Creating keys or API searches requires eligible access. |
| 404 | The run ID is unknown or does not belong to the authenticated account. |
| 429 | Throttle requests. Honor Retry-After when supplied; otherwise back off with jitter. |
| 5xx | A service-side failure. Retry reads with bounded backoff; do not blindly retry charged submissions. |
{
"detail": {
"error": "invalid_request",
"message": "query is required"
}
}Use the deployed limits
Create, read, and stream endpoints have separate rate limits. Read the live values from GET /v1/capabilities, under limits.rate_limit_per_minute, read_rate_limit_per_minute, and stream_rate_limit_per_minute.
Rate limits count API requests, not individual modules. Bound concurrency across your application’s workers. A faster polling interval does not make modules execute faster.
Avoid duplicate charged searches
Save run_id as soon as you receive it. On a read timeout, SSE disconnect, or reconnect event, resume with GET using that ID.
Do not turn every empty result or module timeout into another full search. Preserve partial results and expose coverage to your users.