Rate limits and errors

Rate limits#

• Each key may make 10 requests per second sustained, with a burst of 60.
• Each organisation may trigger up to 60 flow runs per minute and begin up to 120 uploads per minute (every file in a batch counts). These caps apply across all of the organisation's keys.

Over a limit the API answers 429 rate_limited with a Retry-After header (in seconds). Wait that long and retry. Polling a run once every few seconds, or uploading files one after another, stays comfortably inside the limits.

The error shape#

Every error has the same shape:

{
  "error": {
    "code": "validation_failed",
    "message": "The request is invalid.",
    "details": [{ "field": "limit", "message": "Number must be greater than or equal to 1" }],
    "request_id": "0b2d1c4e-..."
  }
}

details is present when there is something specific to say: a list of { field, message } entries for a validation failure, or an object such as { "reason": "render_locked" } for a conflict.

A path that does not exist under /api/v1 answers 404 not_found in the same shape. Every error carries only these fields; nothing about Nubu's internals rides an error.

When storage is full#

The API never bypasses the organisation's storage allowance: it stops exactly where the app would, and says so.

• Beginning an upload or a replacement (assets and templates, single or batch) whose file would not fit the remaining storage answers 409 conflict with details.reason storage_full; the message says how much is free. In a batch, that file's entry carries the error and the others proceed.
• Approving or re-rendering a creative while storage is full answers 409 conflict with details.reason storage_full: new renders are paused.
• Triggering a flow with auto_queue: true still builds (202), but the creatives wait in review: the answer and the run carry "queue_fallback": "storage" and a notice saying why. Approve them once space is free.
• If an organisation goes over its allowance while renders are queued (output sizes are only known when they land), the queued creatives are failed with the storage message and the run reports them as render_failed; re-render them once space is free.

Free space by deleting assets, templates or renders, through the API or the app: the accounting updates at once and the gates lift with it.

Retrying#

• Retry 429 after Retry-After, and 500 with a short backoff.
• Never retry a 4xx other than 429 without changing the request.
• Completing an upload twice, or triggering the same flow twice, creates nothing twice: a completed upload answers the same asset again, and each trigger is its own run. Use external_id on a trigger to recognise your own runs.