Errors
What each status code means and what to do about it.
Every error has the same shape:
{
"code": "PAYMENT_REQUIRED",
"status": 402,
"message": "Your balance is too low to start this generation.",
"requestId": "s1383pvtrrae52faz9zs23jv"
}Branch on status or code, never on message — the wording is meant for a
person to read and may change. Validation failures add a data.issues array
naming the fields at fault.
| Status | Meaning | What to do |
|---|---|---|
400 | The request was rejected — a missing or invalid field, or an assetId that is not a usable upload of yours. | Fix the request. Retrying it unchanged will not help. |
401 | No key, a malformed key, or an unknown key. | Check the Authorization header. All three cases answer identically. |
402 | Your balance is too low to start this generation. | Add funds. Nothing was reserved. |
404 | No such task or upload belonging to you. | Check the id. Another account's id answers the same way as one that does not exist. |
409 | The task cannot make that transition — cancelling one that has already started. | Read the task's current status. |
413 | The request body is larger than 64 KB. | Shorten the prompt. Images go through uploads, not the body. |
429 | Too many requests. The limit is 60 generations per minute per account. | Wait for Retry-After seconds, then retry. |
500 | Something went wrong on our side. | Retry. If it persists, quote the requestId. |
503 | That configuration is not currently on sale, or the provider is unavailable. | Try another tier, or retry later. Nothing was reserved. |
code mirrors the status — BAD_REQUEST, UNAUTHORIZED, PAYMENT_REQUIRED,
NOT_FOUND, CONFLICT, PAYLOAD_TOO_LARGE, TOO_MANY_REQUESTS,
INTERNAL_SERVER_ERROR, SERVICE_UNAVAILABLE — with one exception,
IDEMPOTENCY_KEY_REUSED, which is also a 409.
Nothing is charged for a failed request
A rejected request reserves nothing. A generation that is accepted reserves its cost immediately, and that reservation is refunded in full if the work fails or is cancelled before it starts. You are only charged for a generation that produced a result.
Reporting a problem
Every response carries an X-Request-Id header, and every error repeats it as
requestId. Log it. When something goes wrong, send us:
- the
requestId, or thetaskIdif you have one; - roughly when it happened, with a timezone;
- what you expected and what you got.
That is enough to find the request. Never send us your API key, your password, or any payment credential — we cannot use them, and no one at PierNode will ask for them.
Not found means not yours
An id belonging to another account and an id that never existed both return
404, with the same body. This is deliberate: otherwise the difference between
the two answers would reveal which ids are real.