Reference · Errors

Photta API errors every type and what to do

In one sentence

Every Photta API failure returns the same shape: a status, an `error.type`, a message and a `request_id`. Retry 429 after the Retry-After header and 5xx with backoff; fix 400, 401 and 402 in your own code.

Get an API keyRead the docs
  • Errors: 7 error types
  • Retry-After: Retry-After: 30s
  • Limits: 600 requests/min

Every figure on this page comes from the Photta API docs · checked

Error types

The complete list the API documentation publishes.

400invalid_request_error
The request is malformed or contains invalid parameters.
401authentication_error
The API key is missing, invalid, or expired.
402insufficient_credits_error
Your account does not have enough credits.
404not_found_error
The requested resource does not exist.
409conflict_error
The request conflicts with current state — e.g. your concurrent-batch cap is reached.
429rate_limit_error
Too many requests. Slow down and retry.Retry-After: 30
500api_error
An internal server error occurred. Retry later.

The shape of an error

The same envelope on every endpoint, whatever went wrong.

{
  "error": {
    "type": "rate_limit_error",
    "message": "Rate limit exceeded."
  },
  "request_id": "req_xxxxxxxx"
}

Handling failures

  • Respect Retry-After

    A 429 carries a Retry-After header. Wait that many seconds, then retry with exponential backoff — retrying immediately only pushes the next window further away.

  • Failures refund credits

    A generation that fails after being accepted refunds its credits automatically, so a retry does not double-charge.

  • Quote the request id

    Every response carries a `request_id`. Log it. It is the fastest way for support to find one specific failure among thousands.

  • 409 is a queue signal

    A conflict means your plan’s concurrent-batch cap is reached. Poll the batch already in flight until it resolves, then resubmit — do not spin.

Questions about API errors

What does an error body look like?

An `error` object with a `type` and a `message`, alongside the `request_id`. The type is stable and machine-readable; the message is for humans and may change.

Which errors are worth retrying?

429 after waiting the Retry-After seconds, and 5xx with exponential backoff. A 400, 401 or 402 will fail the same way until something on your side changes.

What does a 402 mean?

`insufficient_credits_error` — the account does not hold enough credits for the call, or for the whole reservation in a batch. Nothing is generated and nothing is charged.

How do I report a failure?

Send the `request_id`, the endpoint and the time. That triple identifies the exact call; the image itself is not needed to look it up.

Endpoints and references

Every figure on this page comes from the Photta API docs · checked

Try the API in five minutes

Generate a Photta API key, paste the cURL snippet above, and you'll have your first on-model image before the coffee finishes brewing.

Create an account and get an API keyAPI
  • 7 error types
  • Retry-After: 30s
  • 600 requests/min