Error Handling

Error response format

All errors follow the same JSON envelope. The status field contains the error code, and message describes the failure. The optional data field may include additional context.

{
  "status": "VALIDATION_ERROR",
  "message": "Invalid promptVersionId",
  "data": null
}

Error codes

HTTP	status code	Description
400	BAD_REQUEST_ERROR	The request was malformed.
401	UNAUTHORIZED_ERROR	Missing or invalid API key.
402	PAYMENT_REQUIRED_ERROR	Not enough credits or need to upgrade to a Pro plan.
404	NOT_FOUND_ERROR	The requested resource was not found.
410	GONE_ERROR	The resource is no longer available.
422	VALIDATION_ERROR	Input failed validation; see data for details.
429	TOO_MANY_REQUESTS_ERROR	Rate limit exceeded. See Rate Limits.
500	SERVER_ERROR	Internal server error.
504	GATEWAY_TIMEOUT_ERROR	The operation did not finish within the time window.

Handling common errors

401 — Unauthorized

Your API key is missing, invalid, or has been revoked. Double-check the Authorization: Bearer <key> header and verify your key on the API Keys page.

402 — Payment required

Your credit balance is too low or your Pro subscription has lapsed. Check your balance with GET /v1/me/credits and top up in your account.

422 — Validation error

The request body or parameters failed validation. Common causes:

• Invalid UUID format for promptVersionId, promptId, or runId
• Missing required fields in inputs
• Image input count doesn't match the prompt's imageCount
• Invalid runOptions keys for the selected model

The message field describes what went wrong.

429 — Rate limited

You've exceeded the 5 requests/second limit. Read the Retry-After header and wait before retrying. See Rate Limits for details on headers and strategies.

504 — Gateway timeout

The run didn't finish within the two-minute window. This is not a failure — the run is still processing. Use the runId from the data field to poll for results:

curl "https://api.betterprompt.me/v1/runs/<RUN_ID>" \
  -H "Authorization: Bearer $BETTERPROMPT_API_KEY"

Retry strategies

• Don't retry 400, 401, 402, 404, 410, 422 — these are client errors that won't resolve on retry.
• Retry with backoff for 429 — wait the Retry-After duration, then retry.
• Retry with backoff for 500 — occasional server errors may be transient.
• Poll instead for 504 — don't re-create the run; poll the existing runId.