OMSCourse Search API
DemoAPI reference
API reference

Errors & rate limits

Every error uses one shape, with a stable machine-readable code.

Error response
HTTP/1.1 429 Too Many Requests
Retry-After: 23
X-Request-Id: req_7FhyGQo9V1qL3T7MuRE6

{
  "request_id": "req_7FhyGQo9V1qL3T7MuRE6",
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limited",
    "message": "Too many requests. Retry after the number of seconds in the Retry-After header."
  }
}

Error codes

invalid_request
400 · invalid_request_error
The request body is invalid.
query_too_long
400 · invalid_request_error
query must be at most 500 characters.
invalid_context
400 · invalid_request_error
context is invalid or expired. Start a new conversation by sending context: null.
missing_api_key
401 · authentication_error
Provide your API key as 'Authorization: Bearer <key>'.
invalid_api_key
401 · authentication_error
The API key is not valid.
key_revoked
403 · authentication_error
This API key has been revoked or has expired.
rate_limited
429 · rate_limit_error
Too many requests. Retry after the number of seconds in the Retry-After header.
daily_budget_exhausted
503 · service_error
The daily search capacity has been reached. Service resumes at midnight UK time.
demo_daily_cap
503 · service_error
The public demo has reached today's limit. Please try again tomorrow.
ai_unavailable
503 · service_error
The AI service is temporarily unavailable. Please retry shortly.
timeout
504 · service_error
The search took too long. Please retry.
internal_error
500 · api_error
An unexpected error occurred.

What to retry

  • Retry 429, 503 and 504 once, after Retry-After seconds (or 5 seconds if absent). Show the visitor a friendly "try again" message meanwhile.
  • Don't retry 400, 401 or 403. Fix the request or key.
  • Log request_id for anything unexpected.

Rate limits

Limits are per key and enforced across all concurrent requests. Default limits:

Production key (oms_live_)
30 requests per minute · 3,000 per day · 5 at the same time
Test key (oms_test_)
10 requests per minute · 300 per day · 2 at the same time

Daily limits reset at midnight UK time. OMS can raise limits on request. A service-wide daily capacity also applies (503 daily_budget_exhausted); you are unlikely to reach it in normal use.

Timeouts

Searches usually take 4–8 seconds. The API gives up after 25 seconds with 504 timeout. Set your HTTP client timeout to 30 seconds.