Errors | EZGH Cloud

The error body every EZGH Cloud API returns, its status codes and error codes, and which errors to retry.

Every error response has the same JSON body:

{ "error": { "code": "access_denied", "message": "You're not allowed to projects.delete" } }

code is stable. Branch on it.
message is for people and can change.
Some errors add fields next to code and message: issues for invalid_request, quota for quota_exceeded, and line and column for Trails’ invalid_query.

A validation failure lists every problem, with the path of the field:

{
  "error": {
    "code": "invalid_request",
    "message": "Request validation failed",
    "issues": [{ "path": "limit", "message": "must be an integer from 1 to 100" }]
  }
}

Status codes

Status	Code	Meaning
400	`invalid_request`	The body, path or query is malformed, or `limit` is out of range.
400	`invalid_cursor`	The cursor was changed, or belongs to another list, filter or organization.
401	`unauthenticated`	No credential, or one that isn’t valid.
403	`access_denied`	Your policies don’t allow the action. The message names it.
403	`forbidden`	Policies can’t grant this, or not with this credential, for example deleting the organization with an API key.
404	`not_found`	The resource doesn’t exist, its ID is malformed, or it’s in an organization you don’t belong to.
409	`idempotency_conflict`	The `Idempotency-Key` was used for a different request.
409	`idempotency_in_progress`	The first request with this `Idempotency-Key` hasn’t finished. Has `Retry-After`.
409	`quota_exceeded`	An allocation quota is full, such as projects per organization. Has `quota`.
412	`precondition_failed`	The `If-Match` header doesn’t match the resource’s current `ETag`. Nothing changed.
413	`payload_too_large`	The request body is over the operation’s limit.
429	`too_many_requests`	You’re over a rate limit. Has `Retry-After`.
429	`quota_exceeded`	A rate, usage or concurrency quota is spent. Has `quota`.
500	`internal_error`	A problem on EZGH Cloud’s side. The message is “Something went wrong”.
503	`unavailable`	A service the request needs is unavailable. Has `Retry-After`.

Operations can return their own codes as well, such as organization_exists and managed_by_scim. Each operation’s page in the API reference lists its responses.

Organizations you don’t belong to

A request for an organization you don’t belong to returns 404 not_found with the message Organization not found, the same as for an organization that doesn’t exist. Other people’s organizations can’t be discovered by probing IDs.

Quota errors

quota_exceeded has a quota object that names the quota (id), its limit and how much is used. It never has Retry-After: waiting doesn’t free an allocation. Delete something, or wait for the rate window or billing period the quota describes. See Service quotas.

Retrying

Response	Retry
`429 too_many_requests`, `503 unavailable`, `409 idempotency_in_progress`	After the `Retry-After` seconds
`429 quota_exceeded`, `409 quota_exceeded`	Not until usage is below the limit
Other `4xx`	Not without changing the request
`500 internal_error`, or no response	With the same `Idempotency-Key`, where the operation takes one

Retry-After is a whole number of seconds.