Authentication

Errors

The Oceanir API uses standard HTTP status codes and returns structured JSON error responses. This reference covers every error you may encounter.

Error format

All errors return a JSON object with success: false and a descriptive error message.

Standard Error Response

{
  "success": false,
  "error": "Invalid API key",
  "request_id": "req_8X_hBwW2"
}

HTTP status codes

Status	Meaning	Resolution
401	Invalid or missing API key	Check your `x-api-key` header
402	Insufficient credits	Purchase credits or upgrade your plan
422	Unprocessable image	Verify image dimensions and file format
429	Rate limit exceeded	Pause requests for the duration of `retry_after`
502	Analysis engine error	Temporary failure. Retry after 30 seconds

Retry strategy

For transient server errors (429, 502, 503), we recommend implementing exponential backoff with jitter.

Python Implementation

import time, random

def call_with_retry(func, max_retries=3):
    for attempt in range(max_retries):
        try:
            return func()
        except RateLimitError as e:
            # wait = (2^attempt) + random jitter
            wait = (2 ** attempt) + random.uniform(0, 1)
            time.sleep(wait)
    raise Exception("Max retries exceeded")

Need help?

If you encounter an error not listed here, contact support@oceanir.ai with the request_id and a brief description of the payload.