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

# Errors

> Error format, error codes and what to retry.

Every error returns the same JSON body:

```json theme={null}
{
  "error": {
    "code": "hostname_taken",
    "message": "A server or order on your account already uses this hostname.",
    "details": null
  }
}
```

| Field | Description |
| - | - |
| `code` | Stable code. Branch on it. |
| `message` | For people. May change. |
| `details` | Extra data or `null`, such as `details.amount` on `409 price_changed`. |

New codes may be added; handle unknown ones by HTTP status.

## Validation Errors

Invalid input returns `422 validation_error`, with each problem in `details.fields`; `field` is `body.<name>`, `query.<name>` or `path.<name>`.

```json theme={null}
{
  "error": {
    "code": "validation_error",
    "message": "The request has invalid fields.",
    "details": {
      "fields": [
        {"field": "body.hostname", "message": "String should match pattern '^[A-Za-z0-9]([A-Za-z0-9-]{0,61}[A-Za-z0-9])?$'"}
      ]
    }
  }
}
```

Unknown body fields and `null` for a field that doesn't take it also return `422`; omit the field instead.

## Error Codes

| HTTP | Code | Description |
| - | - | - |
| `400` | `bad_request` | Not possible as sent; `message` says why. |
| `400` | `invalid_promo_code` | Unknown, expired or not valid for this order. |
| `400` | `invalid_plan`, `ineligible` | Can't resize to this plan. |
| `401` | `invalid_token` | Missing, malformed, unknown or deleted. |
| `401` | `token_disabled` | Token disabled. |
| `401` | `token_expired` | Token expired. |
| `402` | `authentication_required` | Bank requires 3D Secure. |
| `402` | `card_declined` | Bank declined the charge. |
| `402` | `no_payment_method` | No saved card. |
| `402` | `payment_failed` | Card payment couldn't start. |
| `403` | `account_disabled` | Account disabled. |
| `403` | `api_access_disabled` | API isn't enabled for your account. |
| `403` | `billing_mismatch` | Resize only: server billing doesn't match your account. |
| `403` | `email_not_verified` | Email not verified. |
| `403` | `insufficient_scope` | `read` token on a write endpoint. |
| `403` | `orders_disabled` | New orders are paused. |
| `404` | `not_found` | Unknown path or ID, or another account's ID. |
| `405` | `method_not_allowed` | Path doesn't take this method. |
| `409` | `conflict` | Current state doesn't allow this; each endpoint lists its causes. |
| `409` | `hostname_taken` | A server or open order uses this hostname. |
| `409` | `out_of_stock` | Plan sold out at this location. |
| `409` | `payment_pending` | Charge unknown; don't retry. See [Create Errors](/api-reference/creating-servers.md#create-errors). |
| `409` | `promo_changed` | Promo code no longer makes the order free. |
| `409` | `price_changed`, `vm_state`, `pending`, `unpaid_invoice`, `subscription_not_active`, `cancel_scheduled`, `cancelled`, `refund_pending`, `unsupported_subscription`, `unknown_plan`, `unknown_price`, `no_billing_period` | Resize refused. See [Resize Outcomes](/api-reference/creating-servers.md#resize-outcomes). |
| `413` | `payload_too_large` | Request body over 64 KB. |
| `422` | `validation_error` | Invalid body, query or path field. |
| `429` | `rate_limit_exceeded` | Rate limit reached. |
| `500` | `internal_error` | Unexpected server error. |
| `503` | `billing_unavailable` | Resize only: billing is briefly unavailable. |
| `503` | `service_unavailable` | Host node or card payments unavailable. |

No `402` charges your card.

## What to Retry

| Response | Action |
| - | - |
| Any error with `details.order_intent_id` | Don't retry. Contact support with that ID. |
| `429` | Wait `Retry-After` seconds, then retry. |
| Network error, `500` or `503` | Retry with backoff. See [Safe Retries](/api-reference/creating-servers.md#safe-retries). |
| `409 promo_changed` | Send the same request again. |
| Any other `4xx` | Fix the request first. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.