Skip to main content
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: 
{
  "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
  }
}
FieldAlways presentDescription
exception_classYesMachine-readable error type
messageYesHuman-readable description
request_idYesUnique ID for this request — include when contacting support
infoNoExtra structured data for specific error types (quotas, invalid fields)
invalid_fieldsNoField-level validation errors

​
Common error types

​
ValidationError

The request body is missing required fields or contains invalid values. 
{
  "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: 
{
  "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. 
{
  "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. 
{
  "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:

​
ForbiddenError

The request is structurally valid but cannot be fulfilled — typically because a flavor has reached regional capacity. 
{
  "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. 
{
  "exception_class": "HTTPError",
  "message": "HTTP 405: Method Not Allowed",
  "request_id": "4cf1202f8e35e9ddaabae6c5c23e1251"
}
Check the API reference for the correct HTTP method for the endpoint.

​
Authentication errors

All authentication errors return HTTP 401. The message text identifies the specific cause:
MessageCause
Authentication credentials were not provided.No Authorization header
Bad permanent token: {partial_key}Token truncated at $ — shell expansion issue
Token is invalid or expiredToken deleted or past expiry date
Given token not valid for any token typeWrong auth scheme — use APIKey, not Bearer

​
HTTP status codes

Every error response includes an HTTP status code that identifies the error category:
StatusTypical exception_class
400ValidationError
401not_authenticated, token_not_valid
403ForbiddenError, permission denied
404NotFoundError
405HTTPError
409ConflictError (resource already exists)
429Rate limit exceeded
500Internal 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 to identify the request in the infrastructure logs.
Error typeSafe to retry?Action
ValidationErrorNoFix the request first
NotFoundErrorNoCheck IDs and region
QuotaLimitExceedNoRequest quota increase
ForbiddenError (capacity)Yes, in different region/flavorChoose different region
HTTPError 405NoFix the HTTP method
500Yes, with exponential backoffWait 1–5s and retry up to 3 times
429Yes, after waitingRespect Retry-After header if present