Using the API

Errors

Status codes, and the details that make a refusal actionable.

Errors are gRPC statuses with google.rpc details attached. Read the details. A bare code says little; the details say what was wrong and, usually, where to go to fix it.

Codes you will meet

Code	Means	Retry?
`INVALID_ARGUMENT`	The request is malformed, or asks for something that can never be satisfied.	No
`NOT_FOUND`	No such resource, or you cannot see it.	No
`ALREADY_EXISTS`	That id is taken.	No
`PERMISSION_DENIED`	You lack a permission on that resource. The message names it.	No
`UNAUTHENTICATED`	No credential, or one that is invalid, expired or revoked.	After fixing the credential
`FAILED_PRECONDITION`	The resource or account is not in a state for this — including insufficient credit and a plan that does not include the feature.	After fixing it
`RESOURCE_EXHAUSTED`	A quota limit.	After an increase
`ABORTED`	A concurrent change: the `etag` you sent is stale.	Yes, after re-reading
`UNAVAILABLE`	Transient — no capacity right now, or a brief outage.	Yes
`DEADLINE_EXCEEDED`	The call ran out of time.	Yes
`INTERNAL`	Plany's fault. Carries a trace id.	Yes

Retry UNAVAILABLE, DEADLINE_EXCEEDED and ABORTED with backoff. When an error carries a RetryInfo, wait the delay it gives rather than choosing your own.

Quota versus credit

These are different errors with different remedies. Quota is raised by asking; credit is raised by paying.

RESOURCE_EXHAUSTED, with a google.rpc.QuotaFailure naming the metric and, usually, a google.rpc.Help link to request more:

text

1code:    RESOURCE_EXHAUSTED
2message: "the request would exceed the playpute.plany.cloud/game_server_groups
3          quota (limit 2 groups, 2 in use)"
4details:
5  QuotaFailure:
6    violations:
7      - subject: "playpute.plany.cloud/game_server_groups"
8  Help:
9    links:
10      - description: "Request a higher playpute.plany.cloud/game_server_groups limit"
11        url:         "https://plany.cloud/quotas?consumer=projects/"

Every quota can be raised by asking. See Quotas.

FAILED_PRECONDITION, with a google.rpc.PreconditionFailure of type INSUFFICIENT_CREDIT:

text

1code:    FAILED_PRECONDITION
2message: "account accounts/ has insufficient credit for this
3          operation (balance $0.00)"
4details:
5  PreconditionFailure:
6    violations:
7      - type:    "INSUFFICIENT_CREDIT"
8        subject: "accounts/"
9  Help:
10    links:
11      - description: "Add credit to this account"
12        url:         "https://plany.cloud/billing"

See Billing.

FAILED_PRECONDITION, with a PreconditionFailure and an ErrorInfo whose reason is PLAN_REQUIRED, and a Help link to upgrade. A feature such as spot is on the Pro plan; an account on Hobby is told so rather than refused without a reason.

Capacity

UNAVAILABLE, with ErrorInfo { reason: "NO_CAPACITY", domain: "plany.cloud" } and usually a RetryInfo.

This is transient: more room is being made. Wait the RetryInfo delay and try again.

INVALID_ARGUMENT, with ErrorInfo { reason: "INFEASIBLE_PLACEMENT" }.

The request asks for something no machine can satisfy. Retrying will never help, which is why this is not UNAVAILABLE — change the request instead.

RESOURCE_EXHAUSTED, with ErrorInfo { reason: "NO_ALLOCATABLE_GAME_SERVER" }, from AllocateGameServer. Nothing matching your selectors is ready: try again shortly, or let your fleet grow.

Other details you will see

Detail	On
`ResourceInfo`	`NOT_FOUND` and `ALREADY_EXISTS` — the resource type and name.
`BadRequest`	`INVALID_ARGUMENT` — which field, and why.
`PreconditionFailure`	`FAILED_PRECONDITION` — a typed violation.
`ErrorInfo`	A machine-readable `reason` in domain `plany.cloud`.
`RetryInfo`	How long to wait before retrying.
`Help`	Where to go to fix it.

Internal errors

An INTERNAL error's message and its ErrorInfo carry a trace id. Quote it when you open a support case — it is what lets Plany find your exact request.

Errors that look like something else

NOT_FOUND for something you know exists›

You may not have permission to see it. Where knowing that a resource exists would itself tell you something — a network in a project you have no access to, for instance — Plany answers NOT_FOUND rather than PERMISSION_DENIED. Check the name, then check your role on the project.

FAILED_PRECONDITION at sign-in listing accounts›

You belong to several accounts and named none. Choose one with plany auth login --account, or pass account on IssueToken.

Everything refused after signing in with a one-time password›

A session from a one-time password can only change the password. Choose a new one — the console asks you to straight away — and sign in again.