Errors

Every v1 API error comes in the same envelope:

{
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "message": "This token was not granted write access to this resource.",
    "details": { "required": ["write", "all"], "granted": ["read"] }
  }
}

Compare code, which is stable. message is for people and may change. details appears when there is something to detail.

Codes

Status	code	When
400	VALIDATION_ERROR	invalid body, filter, sort or cursor
401	INVALID_TOKEN, INVALID_AUDIENCE, INVALID_ISSUER, TOKEN_EXPIRED, TOKEN_REVOKED	access token problem (Authentication)
403	UNKNOWN_ORGANIZATION	the token's organization is not in Kadu
403	INSUFFICIENT_SCOPE	the token lacks the route's scope (Permissions)
403	USER_PERMISSION_DENIED, NOT_A_MEMBER	the role of the token's person does not allow it
403	FEATURE_NOT_ENABLED	Kobana has not enabled this operation for the organization
403	ENTITLEMENT_REQUIRED	run without Kadu in the organization's plan
404	NOT_FOUND	the resource does not exist, was removed or belongs to another organization
409	CONFLICT	state conflict (for example, environment name already in use)
409	IDEMPOTENCY_KEY_REUSED, IDEMPOTENCY_REQUEST_IN_PROGRESS	see Idempotency
413	PAYLOAD_TOO_LARGE	body above 1 MiB
422	MISSING_SECRETS	run with required secrets that have no value in the environment
422	ENVIRONMENT_REQUIRED	run without a valid environment
422	COST_LIMIT_REACHED	the organization reached the monthly cost cap
429	RATE_LIMITED	request limit (Limits)
500	INTERNAL_ERROR	our failure. The message never carries internal details.
503	AS_UNAVAILABLE	token verification is unavailable. Try again after Retry-After.

Besides these, a route may return its own code, documented in its reference.

What to do

Status	Retry?
4xx	No: the same request will fail again. Fix the cause.
409 IDEMPOTENCY_REQUEST_IN_PROGRESS	Yes, after a few seconds, with the same key.
429	Yes, after Retry-After.
5xx	Yes, with increasing wait and the same X-Idempotency-Key on writes.

The run endpoint uses the same envelope, with the lowercase codes listed on its page.