---
title: "Errors & Credit Model"
description: "Understanding API error response payloads, status codes, and credit deduction rules."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.svgdiagram.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors & Credit Model

This page details standard error handling, HTTP status codes, and credit funding/refund logic in `svgdiagram.ai`.

---

## Standard Error Format

API errors may return a JSON payload with these fields. Some framework-generated errors, such as HTTP exceptions, may instead be plain text. Clients should handle both formats.

```json
{
  "error": "Human-readable description of what went wrong",
  "code": "specific_error_code",
  "details": "optional error-specific data"
}
```

---

## HTTP Status Codes

| Status Code | Code Identifier | Description & Resolution |
| :--- | :--- | :--- |
| `400 Bad Request` | `validation_failed`, `invalid_parameters`, `invalid_options`, `export_error` | Invalid request data, design parameters, options, or export settings. |
| `402 Payment Required` | `insufficient_credits` | No eligible credits remain for the request. Add credits at [https://svgdiagram.ai/billing](https://svgdiagram.ai/billing). |
| `502 Bad Gateway` | `generation_provider_failed`, `design_selection_failed`, `generation_invalid_output`, `renderer_failed` | A model provider, design selection, generated output, or renderer failed. |
| `503 Service Unavailable` | `over_capacity` | The service is temporarily at capacity. Retry later. |
| `504 Gateway Timeout` | `generation_timeout` | Generation timed out. |
| `500 Internal Server Error` | `internal_error` | An unexpected server error occurred. |

---

## Credit Lifecycle & Refunds

Every paid model operation follows a strict, fair credit accounting model:

1. **Step 1**

   ### 1. Admission & Credit Hold

   Invalid requests and requests rejected during admission are not charged. Once a generation is admitted and funded, **1 credit** is deducted from the applicable credit balance.
2. **Step 2**

   ### 2. Execution

   The engine invokes the model to select or author the diagram and composes vector outputs.
3. **Step 3**

   ### 3. Completion or Automatic Refund

   - **Success**: The completed diagram is stored, and the response is returned.
   - **Failure after funding**: Failed generations are refunded regardless of their HTTP status. Refunds are applied during failure settlement; the status code alone does not indicate whether a charge was refunded.

> **Tip**
>
> Re-rendering existing diagrams (`POST /rest/v1/generations/:id/render`) and downloading files (`.svg`, `.png`) consume **0 credits**.

Source: https://docs.svgdiagram.ai/errors/index.mdx