Developer API

Reliability, errors, and rate limits

Build retry-safe requests with idempotency, stable error codes, response headers, and cost safeguards.

Updated 30 Sept 2026

On this pageMake every POST idempotent Handle errors by meaning Use stable machine codes Respect RateLimit headers Protect spend

Make every POST idempotent

Send an Idempotency-Key containing 8 to 255 letters, numbers, underscores, or hyphens. The key is scoped per API key and retained for 24 hours; retry the same logical operation with the same value.

POST/api/v1/images200 OK

Request

# identical resend after a network timeout
curl https://oppermind.com/api/v1/images \
  -H "Authorization: Bearer $OPPERMIND_API_KEY" \
  -H "Idempotency-Key: order-58213-hero-image" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"product photo of a walnut desk lamp on white","n":1}'

Response

Idempotent-Replay: trueX-API-Version: 2026-10-01

{
  "model": "oppermind-lato-1-vision",
  "data": [
    {
      "url": "/api/v1/images/proxy?token=…"
    }
  ],
  "usage": {
    "images_generated": 1
  }
}

The retry replays the stored response, marked Idempotent-Replay: true; nothing is generated or charged twice.

Try this

✦POST /api/v1/images Idempotency-Key: order-58213-hero-image {"prompt": "product photo of a walnut desk lamp on white", "n": 1} Then send the identical request again after a network timeout.

What you getThe second call returns the original response instead of generating and charging for a second image; a key shorter than 8 characters is rejected with OPMD_IDEMP_001.

Handle errors by meaning

400 means the request is invalid or asks for something the current model version cannot do (OPMD_CAPABILITY_001), 401 the key is missing or invalid, 402 credits are insufficient, 403 permission, IP or usage policy blocked the call, 404 the file or endpoint does not exist, 409 the same idempotent operation is still running, 413 the body is over 31 MB, 422 a document could not be read, and 429 the rate limit was exceeded. A 502 with OPMD_EMPTY_001 means the model returned no answer, for example it ran out of output tokens, and nothing was charged. Other 5xx responses indicate a gateway or server problem.

POST/api/v1/messages402 Payment Required

Request

curl https://oppermind.com/api/v1/messages \
  -H "Authorization: Bearer $OPPERMIND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"oppermind-lato-1","max_tokens":400,"messages":[{"role":"user","content":"Draft a welcome email for new members."}]}'

Response

X-API-Version: 2026-10-01

{
  "error": {
    "type": "billing_error",
    "code": "OPMD_BILLING_001",
    "message": "Insufficient credits. Add credits at oppermind.com/developers"
  }
}

402 is stop-and-alert, never a retry; only a 5xx api_error is retried, with jitter.

Try this

✦Map status codes to actions in your client: 400 fix the request, 401 check the key, 402 top up credits, 403 check permission or IP allowlist, 409 wait and re-read with the same Idempotency-Key, 413 shrink the request or upload the file first, 429 back off, 502 OPMD_EMPTY_001 raise max_tokens, other 5xx retry with jitter.

What you getA run with an exhausted balance stops at 402 with error.code OPMD_BILLING_001 and alerts finance instead of retrying, while a 5xx retries a bounded number of times.

Use stable machine codes

Branch on error.code rather than parsing prose. Safe messages can be surfaced to users, and X-Request-ID belongs in logs and support reports. When the model rejects a request, for example an unreadable image, the code is OPMD_UPSTREAM_400, error.message gives the reason and nothing is charged. /chat/completions, /responses and /files errors also carry param, the field that caused the error.

POST/api/v1/messages400 Bad Request

Request

curl https://oppermind.com/api/v1/messages \
  -H "Authorization: Bearer $OPPERMIND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"oppermind-lato-1","prompt":"Draft a welcome email for new members."}'

Response

X-API-Version: 2026-10-01

{
  "error": {
    "type": "invalid_request",
    "code": "OPMD_MODEL_001",
    "message": "messages must be a non-empty array."
  }
}

Branch on error.code, show error.message to users as written, keep X-Request-ID for support.

Try this

✦switch (body.error.code) { case 'OPMD_RATE_001': backOff(); break; case 'OPMD_BILLING_001': notifyBilling(); break; default: log(res.headers['x-request-id'], body.error.code); }

What you getEach failure branches on the stable code, error.message can be shown to users as written, and the X-Request-ID sits in your logs for any support report.

Respect RateLimit headers

Every response carries RateLimit information. Slow down before exhausting the budget, add jitter to retryable backoff, and do not retry validation, authentication, permission, or billing failures unchanged.

POST/api/v1/messages429 Too Many Requests

Request

curl https://oppermind.com/api/v1/messages \
  -H "Authorization: Bearer $OPPERMIND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"oppermind-lato-1","max_tokens":60,"messages":[{"role":"user","content":"Tag this ticket: refund request."}]}'

Response

RateLimit-Limit: 120RateLimit-Remaining: 0RateLimit-Reset: 23Retry-After: 23X-API-Version: 2026-10-01

{
  "error": {
    "type": "rate_limit_error",
    "code": "OPMD_RATE_001",
    "message": "Too many requests for this API key. Slow down."
  }
}

Wait RateLimit-Reset seconds plus jitter before retrying; the default budget is 120 requests per minute per key.

Try this

✦After each response read the RateLimit-Remaining header; when it falls below 10 percent of RateLimit-Limit slow your queue, and on a 429 wait for RateLimit-Reset plus random jitter before retrying.

What you getBursts flatten before the limit is hit; a 429 with OPMD_RATE_001 waits out the window, while 400, 401, 402 and 403 responses are never retried unchanged.

Protect spend

Bound max_tokens (default 16384, up to 128000, with reasoning tokens counted as output), image count, duration, and concurrency in your own application. Read the current AUD rates from GET /api/v1/pricing, log billing.charged_aud from every text response, monitor usage and credits, set billing alerts, and place expensive generation behind user authorization.

POST/api/v1/messages200 OK

Request

# max_tokens bounded by your own cap of 1500
curl https://oppermind.com/api/v1/messages \
  -H "Authorization: Bearer $OPPERMIND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"oppermind-lato-1","max_tokens":1500,"messages":[{"role":"user","content":"Write the product page copy for the walnut desk lamp."}]}'

Response

RateLimit-Remaining: 117X-API-Version: 2026-10-01

{
  "id": "req_6c1f9b3e7a5d2c8f4b0e6a1d",
  "model": "oppermind-lato-1",
  "type": "message",
  "content": [
    {
      "type": "text",
      "text": "Warm walnut, clean lines. The lamp gives a soft pool of light for reading and dims to a night glow with one touch."
    }
  ],
  "usage": {
    "input_tokens": 24,
    "output_tokens": 212,
    "cache_read_input_tokens": 0,
    "cache_creation_input_tokens": 0,
    "reasoning_tokens": 0
  },
  "stop_reason": "end_turn",
  "tool_usage": {},
  "billing": {
    "charged_aud": "0.000870"
  }
}

max_tokens bounds the worst case, and billing.charged_aud reports what this request cost.

Try this

✦In your application, cap max_tokens at 1500, image n at 2 and video duration_seconds at 15, run at most 3 generations at once, and require a signed-in user before any /videos call.

What you getSpend stays inside the bounds you set no matter what a user types, and the Developer console's usage view and your billing alerts confirm the pattern rather than surprise you.

GUIDED LEARNING

Practise this in Oppermind Academy

Follow the related tutorial or course and apply the concept to a real task.

Open learning path