Skip to main content
This page documents how to handle failures when calling the Omium HTTP API. For endpoint details, start at API overview.

​
Error handling basics

Omium APIs use standard HTTP status codes. Treat non-2xx responses as failures and log the response body for debugging.
StatusMeaningWhat to do
400Invalid request (missing fields, invalid enum)Fix the request payload; don’t retry unchanged.
401Missing / invalid API keyCheck X-API-Key and account; rotate key if needed.
403Key is valid but not allowedCheck tenant/workspace permissions and feature access.
404Resource not foundValidate IDs; don’t retry unless you expect eventual consistency.
409ConflictTreat as state mismatch; refetch and decide.
413Payload too largeReduce payload size; use files or references if supported.
422Validation failedFix the request; don’t retry unchanged.
429Rate limitedBack off and retry with jitter.
5xxServer-side errorRetry with exponential backoff; alert if sustained.

​
Common patterns

​
Idempotency and retries

If you’re building an orchestrator or worker system:
  • Retry only when it’s safe (typically 429 and 5xx).
  • Use exponential backoff with jitter.
  • If you supply your own execution_id (where supported), you can make retries safer by de-duplicating on your side.

​
Logging

Always log:
  • request path + method
  • response status code
  • response body (redact secrets)
  • correlation IDs if your stack has them

​
Rate limits

Rate limits protect platform capacity. You may see 429 during bursts or when a tenant hits its limit. Recommended client behaviour on 429:
  1. Wait using exponential backoff + jitter
  2. Retry the same request
  3. If it repeats, reduce concurrency and/or request volume
Example (pseudo): 
sleep = min(base * 2^attempt + random(0..jitter), max_sleep)

​
Next steps

Executions

Create runs and drive replay/rollback.

API overview

Base URL, auth, and resource map.