Developer API
Reliability, errors, and rate limits
Build retry-safe requests with idempotency, stable error codes, response headers, and cost safeguards.
On this pageMake every POST idempotentHandle errors by meaningUse stable machine codesRespect RateLimit headersProtect 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.
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-06-17
{
"model": "oppermind-lato-1",
"data": [
{
"url": "/api/v1/images/proxy?token=…"
}
]
}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, 401 the key is missing or invalid, 402 credits are insufficient, 403 permission or IP policy blocked the call, 409 the same idempotent operation is still running, 429 the rate limit was exceeded, and 5xx indicates a gateway or server problem.
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-06-17
{
"error": {
"type": "billing_error",
"code": "OPMD_BILLING_001",
"message": "Insufficient credits. Add credits at oppermind.com/developers"
}
}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, 429 back off, 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; keep X-Request-ID with logs and support reports.
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-06-17
{
"error": {
"type": "invalid_request",
"code": "OPMD_MODEL_001",
"message": "messages array is required"
}
}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.
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-06-17
{
"error": {
"type": "rate_limit_error",
"code": "OPMD_RATE_001",
"message": "Too many requests for this API key. Slow down."
}
}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, image count, duration, and concurrency in your own application. Monitor usage and credits, set billing alerts, and place expensive generation behind user authorization.
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-06-17
{
"id": "req_6c1f9b3e7a5d2c8f4b0e6a1d",
"model": "oppermind-lato-1",
"role": "assistant",
"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."
}
],
"stop_reason": "end_turn",
"usage": {
"input_tokens": 24,
"output_tokens": 212
}
}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
Open learning path Practise this in Oppermind Academy
Follow the related tutorial or course and apply the concept to a real task.