Errors

Available

Deployed and supported. The fields and commands described here are stable within version v1alpha1.

All API errors have the same shape, 415 and 429 included:

{"error": "forbidden"}

The message is short, stable, and free of internal details: it names neither a service, nor a path, nor an address. To understand an error, combine the HTTP code, the message, and the context of the request.

Codes

Code	Typical message	Cause	What to do
400	bad request, invalid …, … required	Invalid JSON body, unknown field, malformed name, manifest rejected by the schema, unknown tier	Read the message: it names the field or rule at fault. Unknown fields are refused.
401	unauthorized	Token missing, expired, invalid signature, JWT without exp, or session ended by a sign-out	Get an identity again (sng sso login) or reopen a session (POST /v1/iam/session). The CLI does this on its own.
403	forbidden	The session does not have the IAM action required by the route	Check the attached policies (action catalog)
403	tenant session required	The route requires a tenant session and received an identity token	Call POST /v1/iam/session first
403	identity token required	The route requires an identity token and received a session	Use the identity token (/v1/iam/me, /v1/templates, /v1/tenants)
403	forbidden: platform organization required	Tenant creation from an identity outside the StackNGO organization	Sign in with a StackNGO account
404	not found	Resource does not exist in this tenant	Check the name and the current tenant
409	conflict	Name already taken, host already in use, resource being deleted	Choose another name or wait
409	policies_pending	Tenant just created, its policies are not applied yet	Try again after Retry-After seconds (10 s). The CLI waits up to six minutes.
409	tier too small: …	The tenant's tier does not allow the requested resource	Reduce the request or change tier
415	Content-Type must be application/json	Body sent with another type	Add Content-Type: application/json
429	rate limit exceeded	More than 300 requests per minute from your IP address	Wait for Retry-After, smooth out your calls (Limits)
501	feature not available	Feature disabled in this environment (CDN, registrar)	Nothing to do on the client side
502	upstream unauthorized	The secrets service refused the API's call	Try again; if it persists, contact support
503	authorization service unavailable	The authorization service or the quota service is not responding. No access is granted in this case.	Try again with an increasing delay
500	internal server error	Unexpected error	Try again; report it with the time and the route

Principles

• Deny by default. A doubt about a permission, an unavailable authorization service: the response is 403 or 503, never access. A client must not interpret a 503 as "probably authorized".
• No disclosure. A 404 and a 403 may deliberately look alike: the API does not confirm the existence of a resource to someone who is not allowed to read it.
• Stable messages. The messages listed above can be used as keys in a client; the free-form text that sometimes follows them (after : ) may change.

Errors in the CLI

The CLI shows the error message, sometimes followed by an instruction (a 401 becomes session expired: run sng tenant use NAME, a 403 mentions sng tenant policy list), and exits with code 1. With -v, it adds the method and the URL in parentheses. See CLI errors for messages specific to the CLI (not signed in, missing tenant, file not found).

Errors when applying a manifest

A manifest refused by POST /v1/apply responds 400 with a message that names the object and the rule:

{"error": "invalid manifest App/web: spec.services.db: volumes require replicas <= 1 and strategy recreate"}

An accepted manifest can still fail later, during convergence: this does not show in the HTTP response but in the resource's status. See Conditions and reasons.