Errors

The error envelope

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "start_date must be YYYY-MM-DD."
  }
}

Read error.message. When a specific parameter is at fault the message names it, so a client can correct itself without guessing.

Status codes

400

Validation error — check the message in `error.message`.

401

Unauthorized — missing, invalid or revoked bearer token.

403

Forbidden — plan lacks API access, or key is read-only.

404

Not found — the brand, prompt or resource does not exist.

405

Method not allowed.

500

Internal error — logged; retry is safe for reads.

A wrong value is an error, not an empty filter

If you send a value of the wrong type — say limit=many — you get a 400, not a 200 with the filter quietly dropped. That is deliberate: an answer that looks filtered but is not is worse than an error.

Leaving a parameter out, or sending it blank, still falls through to its default.

Not found means not found

A 404 covers both "this does not exist" and "this is not yours". We do not tell the two apart, so you cannot use the API to learn what another workspace holds.

Retrying

Reads are safe to retry. A 500 is logged on our side.

The two write endpoints only add, and adding something that already exists is a no-op, so retrying one of those will not create a duplicate.