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

# Error handling

> Gcore error handling explains response structure, common error types, status codes, and retry strategy for failed requests.

All Gcore API errors share a consistent JSON structure — every response includes an `exception_class`, a human-readable `message`, and a `request_id`.

## Error response structure

Every error response has the same shape:

```json theme={null}
{
  "exception_class": "QuotaLimitExceed",
  "message": "Quota limit for volume_size exceeded by 70",
  "request_id": "f6393419afcfb518a539006f099736da",
  "info": {
    "attribute": "volume_size",
    "current_usage": 20,
    "requested_usage": 120,
    "limit": 50
  }
}
```

| Field | Always present | Description |
| - | - | - |
| `exception_class` | Yes | Machine-readable error type |
| `message` | Yes | Human-readable description |
| `request_id` | Yes | Unique ID for this request — include when contacting support |
| `info` | No | Extra structured data for specific error types (quotas, invalid fields) |
| `invalid_fields` | No | Field-level validation errors |

## Common error types

### ValidationError

The request body is missing required fields or contains invalid values.

```json theme={null}
{
  "exception_class": "ValidationError",
  "message": "Validation Error: {'interfaces': ['Field required'], 'volumes': ['Field required']}",
  "request_id": "af999e5f3b091aad111442fff86b3658",
  "invalid_fields": {
    "interfaces": ["Field required"],
    "volumes": ["Field required"]
  }
}
```

`invalid_fields` lists each problematic field and why it failed. Fix the request body and retry.

A `ValidationError` also appears when a reseller account requires specific name templates:

```json theme={null}
{
  "exception_class": "ValidationError",
  "message": "Following name templates are not allowed for this client: ['my-vm'], use one of ['frn-c2-{ip_octets}']"
}
```

### NotFoundError

The requested resource does not exist, or exists in a different project or region.

```json theme={null}
{
  "exception_class": "NotFoundError",
  "message": "Instance 726ecfcc-7fd0-4e30-a86e-7892524aa483 could not be found",
  "request_id": "681423d626cb6c252c73a97211efb7e3"
}
```

Check that the resource ID is correct and that `project_id` and `region_id` in the path match the region where the resource was created.

### QuotaLimitExceed

The request would exceed a project or account quota.

```json theme={null}
{
  "exception_class": "QuotaLimitExceed",
  "message": "Quota limit for volume_size exceeded by 70",
  "request_id": "f6393419afcfb518a539006f099736da",
  "info": {
    "attribute": "volume_size",
    "current_usage": 20,
    "requested_usage": 120,
    "limit": 50
  }
}
```

`info` shows the exact numbers: current usage, requested total, and the limit. To resolve:

* Reduce the requested resource size or count
* Submit a [quota request](/cloud/getting-started/request-a-quota-increase) via the [Gcore Customer Portal](https://portal.gcore.com)

### ForbiddenError

The request is structurally valid but cannot be fulfilled — typically because a flavor has reached regional capacity.

```json theme={null}
{
  "exception_class": "ForbiddenError",
  "message": "The region 6 has reached the limit of flavor g1-standard-2-4",
  "request_id": "d7a764240b3828c4847f692a4f6892ae"
}
```

`ForbiddenError` is not a permissions error — it means the physical resource is temporarily unavailable. Try a different region or a different flavor.

### HTTPError — Method Not Allowed

The HTTP method used is not supported by this endpoint. Most often caused by sending a `GET` to an endpoint that only accepts `POST`, or vice versa.

```json theme={null}
{
  "exception_class": "HTTPError",
  "message": "HTTP 405: Method Not Allowed",
  "request_id": "4cf1202f8e35e9ddaabae6c5c23e1251"
}
```

Check the [API reference](/api-reference/cloud) for the correct HTTP method for the endpoint.

### Authentication errors

All authentication errors return HTTP `401`. The message text identifies the specific cause:

| Message | Cause |
| - | - |
| `Authentication credentials were not provided.` | No `Authorization` header |
| `Bad permanent token: {partial_key}` | Token truncated at `$` — shell expansion issue |
| `Token is invalid or expired` | Token deleted or past expiry date |
| `Given token not valid for any token type` | Wrong auth scheme — use `APIKey`, not `Bearer` |

## HTTP status codes

Every error response includes an HTTP status code that identifies the error category:

| Status | Typical exception\_class |
| - | - |
| `400` | `ValidationError` |
| `401` | `not_authenticated`, `token_not_valid` |
| `403` | `ForbiddenError`, permission denied |
| `404` | `NotFoundError` |
| `405` | `HTTPError` |
| `409` | `ConflictError` (resource already exists) |
| `429` | Rate limit exceeded |
| `500` | Internal server error — transient, retry with backoff |

## Retry strategy

Not every error is worth retrying — the table below distinguishes fixable request problems from transient server conditions. Every response contains a `request_id`; include it when contacting [Gcore support](https://gcore.com/contact-us) to identify the request in the infrastructure logs.

| Error type | Safe to retry? | Action |
| - | - | - |
| `ValidationError` | No | Fix the request first |
| `NotFoundError` | No | Check IDs and region |
| `QuotaLimitExceed` | No | Request quota increase |
| `ForbiddenError` (capacity) | Yes, in different region/flavor | Choose different region |
| `HTTPError 405` | No | Fix the HTTP method |
| `500` | Yes, with exponential backoff | Wait 1–5s and retry up to 3 times |
| `429` | Yes, after waiting | Respect `Retry-After` header if present |