Sume 501 capability_not_configured: no job started, no credits spent

capability_not_configured is a 501. Its published description is plain: the requested generation capability is not connected, no generation job is started and no credits are spent. The body is marked category: runtime_unavailable, stage: runtime, retryable: false, next_action: contact_support, so a retry loop is wrong. The message names the capability, for example "Avatar retrieval is not configured" in the OpenAPI example.

What details tells you

The API builds this error from a capability name and puts two things in details: the capability, and a missing list of the platform pieces that would have to exist: job_storage, api_key_ledger, generation_runtime and usage_ledger. Those are server-side components, so there is nothing for you to add to the request. They tell support where the gap is.

501 is not 503

Do not mix it up with the 503 family. The mapping treats any code that ends in _not_configured, and any 501 or 503 without a more specific rule, as runtime_unavailable with contact_support, and a few 503s are exceptions on purpose:

A safe handler

Branch on retryable and next_action, not on the status number alone. The two 5xx kinds above need opposite behavior:

import json

BODY = '''{"error": {"code": "capability_not_configured", "retryable": false,
 "next_action": "contact_support", "request_id": "req_example",
 "details": {"capability": "Avatar retrieval"}}}'''

err = json.loads(BODY)["error"]
if err["retryable"]:
    print("retry after", err.get("retry_after_seconds") or 30, "seconds")
elif err["next_action"] == "contact_support":
    print("open a ticket with request_id", err["request_id"])
else:
    print("fix the request")

Why you must not retry

The status is 501, which means the server does not support the function that the request needs. In this API that is a platform-wide condition, not a blip, so a retry produces the same answer and adds load. Compare it with queue_full, database_busy or deploy_draining, which all say retryable: true and carry a delay. A good client reads the flag the server sends and does not guess from the digit.

If you run a fallback, route the work to another capability you are allowed to use, or hold it in your own queue until support confirms the fix. Keep the request_id with the held item so that it can be resubmitted with the same Idempotency-Key later, which is safe because no job was created.

What to tell your users

Say that the feature is not available right now, not that their request was wrong, and do not show a retry button. Offer the nearest alternative that your own product supports, for example a different generation type. Log the request_id so that you can match their report to your ticket, and re-test after support confirms the capability is connected.

Before you open the ticket

Check GET /v1/catalog, which lists capabilities, models and runtime readiness, to see whether the capability is advertised for your environment. Include the request_id, the route and the time. No job exists, so there is no status_url to attach. The Errors and credits page covers the rest of the envelope.