Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mayatech.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

Every non-2xx response uses the same envelope. Branch retry policy on type, branch UX on code, surface message to humans, and quote request_id in support tickets. 
{
  "error": {
    "type": "invalid_request",
    "code": "balance_too_low",
    "message": "Team available balance is 1.5 credits, generation requires 2.0.",
    "param": null,
    "doc_url": "https://docs.aurous-labs.com/errors/balance_too_low",
    "request_id": "req_01HXMQ7Z3K8Y2ABCDEFGHJKM"
  }
}

​
Type taxonomy

type is one of five values. The Aurous-Request-Id response header always carries the same value as error.request_id so logging middleware doesn’t need to parse the body.
TypeHTTP statusesExample codes
invalid_request400, 402, 409, 422missing_field, invalid_format, value_out_of_range, unsupported_lora_for_mode, idempotency_key_in_use, generation_not_cancellable, balance_too_low, prompt_blocked, reference_blocked, output_moderation_rejected
authentication401missing_api_key, invalid_api_key, revoked_api_key
not_found404resource_not_found, forbidden_resource (404 by intent — no existence leak)
rate_limit429too_many_requests, concurrency_limit_exceeded
server_error500, 502, 503, 504internal_error, provider_unavailable, provider_timeout
TypeRetry?How
invalid_requestNo. Fix the input.param indicates the offending field. Don’t retry — the same body will fail again.
authenticationNo. Fix the key.Re-fetch the key from your secret store; if revoked, mint a new one.
not_foundNo.Resource doesn’t exist (or isn’t yours). Don’t retry.
rate_limitYes with backoff.Sleep Retry-After seconds (or X-RateLimit-Reset − now). See Rate limits.
server_errorYes with jitter.Exponential backoff: 1s → 2s → 4s → 8s, max ~30s. With an Idempotency-Key, retries are safe — see Idempotency.

​
One example per type

​
invalid_request — 400

curl -X POST https://api.aurous-labs.com/v1/images \
  -H "X-Api-Key: $AUROUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"size": "hd_square"}'

HTTP/1.1 400 Bad Request
Aurous-Request-Id: req_01HXMQ7Z3K8Y2ABCDEFGHJKM
Content-Type: application/json

{
  "error": {
    "type": "invalid_request",
    "code": "missing_field",
    "message": "prompt: must be a string, prompt: must not be empty",
    "param": "prompt",
    "doc_url": "https://docs.aurous-labs.com/errors/missing_field",
    "request_id": "req_01HXMQ7Z3K8Y2ABCDEFGHJKM"
  }
}

​
authentication — 401

curl https://api.aurous-labs.com/v1/balance \
  -H "X-Api-Key: al_live_invalid"

HTTP/1.1 401 Unauthorized
Aurous-Request-Id: req_01HXMQ7Z3K8Y2ABCDEFGHJKM
Content-Type: application/json

{
  "error": {
    "type": "authentication",
    "code": "invalid_api_key",
    "message": "API key is invalid or has been revoked.",
    "param": null,
    "doc_url": "https://docs.aurous-labs.com/errors/invalid_api_key",
    "request_id": "req_01HXMQ7Z3K8Y2ABCDEFGHJKM"
  }
}

​
not_found — 404

A 404 covers both “doesn’t exist” and “exists but not yours.” We never reveal which — same Stripe stance, no existence-leak oracle. 
curl https://api.aurous-labs.com/v1/images/img_99999999999999999999999999 \
  -H "X-Api-Key: $AUROUS_API_KEY"

HTTP/1.1 404 Not Found
Aurous-Request-Id: req_01HXMQ7Z3K8Y2ABCDEFGHJKM
Content-Type: application/json

{
  "error": {
    "type": "not_found",
    "code": "resource_not_found",
    "message": "Generation not found.",
    "param": null,
    "doc_url": "https://docs.aurous-labs.com/errors/resource_not_found",
    "request_id": "req_01HXMQ7Z3K8Y2ABCDEFGHJKM"
  }
}

​
rate_limit — 429

HTTP/1.1 429 Too Many Requests
Aurous-Request-Id: req_01HXMQ7Z3K8Y2ABCDEFGHJKM
Retry-After: 12
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1714752912
Content-Type: application/json

{
  "error": {
    "type": "rate_limit",
    "code": "too_many_requests",
    "message": "Rate limit exceeded for images_post. Retry after 12s.",
    "param": null,
    "doc_url": "https://docs.aurous-labs.com/errors/too_many_requests",
    "request_id": "req_01HXMQ7Z3K8Y2ABCDEFGHJKM"
  }
}
Sleep Retry-After seconds and retry. Don’t hammer — the bucket only refills at the sustained rate.

​
server_error — 5xx

Treat as transient. Retry with exponential backoff. If you sent an Idempotency-Key, the retry is safe even if the original request actually committed. 
HTTP/1.1 503 Service Unavailable
Aurous-Request-Id: req_01HXMQ7Z3K8Y2ABCDEFGHJKM
Content-Type: application/json

{
  "error": {
    "type": "server_error",
    "code": "provider_unavailable",
    "message": "Image provider is unavailable. Please retry.",
    "param": null,
    "doc_url": "https://docs.aurous-labs.com/errors/provider_unavailable",
    "request_id": "req_01HXMQ7Z3K8Y2ABCDEFGHJKM"
  }
}

​
Selected codes

​
balance_too_low

The team’s available balance (credits − pending holds) is less than the cost of the requested generation. Top up via the dashboard /dashboard/billing or wait for pending holds to commit/release. HTTP 402.

​
idempotency_key_in_use

You sent the same Idempotency-Key value with a different request body. Use a fresh key or send the original body to replay. HTTP 409. See Idempotency.

​
too_many_requests

You exceeded the rate limit for this endpoint class. Sleep Retry-After seconds and try again. HTTP 429. See Rate limits.

​
generation_not_cancellable

You called POST /v1/images/:id/cancel on a generation that’s already terminal (succeeded, failed, cancelled, expired, or moderation_rejected). HTTP 400. Idempotent — calling cancel on a row whose hold already resolved is a no-op.

​
forbidden_resource

The resource exists but belongs to another team. We return 404, not 403 — same Stripe stance, no existence-leak oracle.

​
prompt_blocked / reference_blocked

Pre-dispatch moderation classifier rejected the prompt or a reference image. HTTP 400. The prompt is logged but no row is inserted, so there’s nothing to retrieve via GET /v1/images/{id}. (A future date-pin will insert a moderation_rejected row instead, fire image.moderation_rejected webhook, and let you observe the rejection — see the Changelog.)

​
The doc_url convention

Every error code has a deterministic deep-link: https://docs.aurous-labs.com/errors/<code>. Open it in a browser to read this page’s section for the code.

​
Using request_id for support

Every error envelope and every successful response carries a request_id (also surfaced as the Aurous-Request-Id response header). When opening a support ticket, paste at least one request_id so we can pull the exact request from server logs. Example:
Hi support — getting provider_timeout on POST /v1/images for the last hour. request_id: req_01HXMQ7Z3K8Y2ABCDEFGHJKM. Team acme. Thanks.
This shortcuts triage from “let’s look around” to “here’s the exact log line.”

​
Idempotency replay

If you’re retrying a POST /v1/images or /v1/videos after a 5xx, send the same Idempotency-Key you used originally. The platform will replay the cached response — including the original error envelope, if the first call also failed deterministically — instead of creating a duplicate generation. See Idempotency.

​
Headers on every response

  • Aurous-Request-Id: req_<ulid> — quote this in support tickets.
  • Aurous-Version: YYYY-MM-DD — the API version pin applied to this response.
  • X-RateLimit-Limit / X-RateLimit-Remaining / X-RateLimit-Reset — see Rate limits.
  • Retry-After (only on 429) — seconds to wait before retrying.
  • Aurous-Idempotent-Replayed: true (only on idempotency-key replays) — see Idempotency.