Errors in the REST API

When a request fails, the Nebius AI Cloud API returns a status code and an error message. For example:

curl -v -XPOST https://api.nebius.cloud/compute/v1/instances
...
* Request completely sent off
< HTTP/2 400
...
<
* Connection #0 to host api.nebius.cloud left intact
{"code":3, "message":"invalid resource size type: <nil>"}%

The response header contains an HTTP status code, and the response body includes the following:

code: Numeric canonical gRPC status code that correlates with the HTTP status code based on the Google RPC specification.
message: Description of the error.

In this example, the gRPC status code is 3 INVALID_ARGUMENT, which corresponds to 400 Bad Request in HTTP. The Nebius AI Cloud API only uses canonical codes in the full list of gRPC status codes. The following table describes the possible status codes:

gRPC status code	HTTP status code	Description
`0 OK`	`200 OK`	The request completed successfully.
`1 CANCELLED`	`499 Client Closed Request`	You canceled the request.
`3 INVALID_ARGUMENT`	`400 Bad Request`	The request is invalid or is out of the service constraints. Make sure that you specified the method, headers and request body correctly.
`4 DEADLINE_EXCEEDED`	`504 Gateway Timeout`	The request timed out. For requests that change the state of the system, this error may occur even if the request completed successfully but the response was delayed.
`5 NOT_FOUND`	`404 Not Found`	The requested resource doesn’t exist. For example, it may have been deleted. Make sure that you address an existing resource — check its ID or name in the request.
`6 ALREADY_EXISTS`	`409 Conflict`	The resource with the specified parameters already exists. For example, you try to create a virtual machine with the name that another virtual machine already has. To fix the error, use a different name.
`7 PERMISSION_DENIED`	`403 Forbidden`	You don’t have the permission to perform the request. Check that you have the required IAM role. This error is different from `16 UNAUTHENTICATED` because `7 PERMISSION_DENIED` indicates a missing role while `16 UNAUTHENTICATED` points to the incorrect credentials.
`8 RESOURCE_EXHAUSTED`	`429 Too Many Requests`	The quotas of the requested resources are exhausted. Clean up the resources or increase the quotas. If the request tries to exceed the service constraints, another error `3 INVALID_ARGUMENT` occurs.
`9 FAILED_PRECONDITION`	`400 Bad Request`	The request can’t be performed because of the current state of resources. For example, the service only allows deleting empty directories but you try to delete a non-empty one. In that case, first delete resources within the directory and then delete the directory itself.
`10 ABORTED`	`409 Conflict`	The request is aborted, usually due to a concurrency issue such as a resource version mismatch.
`11 OUT_OF_RANGE`	`400 Bad Request`	The request attempts to use a value outside the valid parameter range. Change the value so it’s within the range.
`13 INTERNAL`	`500 Internal Server Error`	An important system condition isn’t met.
`14 UNAVAILABLE`	`503 Service Unavailable`	The service is unavailable. Try again later.
`16 UNAUTHENTICATED`	`401 Unauthorized`	The request is sent with invalid authentication credentials. Check your credentials. This error is different from `7 PERMISSION_DENIED` because `16 UNAUTHENTICATED` only checks the credentials, not roles.

The list doesn’t include the 2 UNKNOWN, 12 UNIMPLEMENTED and 15 DATA_LOSS errors because the REST API by Nebius AI Cloud never returns them.

Developer tools in Nebius AI Cloud

CLI

Terraform provider

REST API

gRPC API

SDKs

Agent Resources