Higgsfield 403 insufficient credits vs Sume 402: handle both

A Higgsfield request with no credits left returns 403, and the docs say it is retryable after funding the account. The Sume equivalent is 402 insufficient_credits: the balance is not enough for the requested generation. The two APIs split the other common errors differently too, so a ported client needs a map, not a rename.

Higgsfield's error table

Higgsfield's errors page lists 500 (retry with backoff), 503 (model disabled or not ready, later), 400 (invalid parameters or concurrency reached), 423 (model temporarily blocked, later), 401 (no), 403 (insufficient credits, after funding), 404 (no) and 422 (validation failed, no). Its authentication page adds that a model your account cannot use can return 404, 423 or 503.

After the submit

Sume's job error categories give the next action for failures that happen after submit: quota means add funds or lower request cost, validation means fix input, and auth means check the API key and workspace access. Failed jobs also carry retryability and retry-after seconds when they apply.

Porting pitfalls

A client that branches on 403 for money will mis-handle Sume. The reverse is also true: a Sume client that treats every 4xx as final will mis-handle a Higgsfield 400 for concurrency, which is retryable after waiting. Branch on the error code string where the API gives one, and on the status where it does not.

• Map Higgsfield 403 to Sume 402 for the top-up path.
• Do not retry a 402 or 422 unchanged on either side.
• Retry 503 later on both, with the same idempotency key.
• Use the Sume request_id when you contact support.

Funding, then retry

For funding errors, the fix is the same on both: add funds, then retry with the same idempotency key so a retry cannot create a second paid job.