IAM API errors

[!caution]

This service is not deployed. There is no iam.shelfcs.com or sts.shelfcs.com in the published endpoint list, and no call on this page will answer. This page is the specification, not a description of something running.

For the identity system that does exist — the identity service users, one project, one role, and EC2 access keys — read Identity, as deployed.

Objective

Read this page to handle IAM errors correctly.

IAM uses the standard query error envelope, which differs from EC2’s. See IAM requests and responses for the shape.

Requirements

• None

Instructions

Authentication and authorisation

Code	Status	Type	Cause
IncompleteSignature	400	Sender	The Authorization header is malformed
SignatureDoesNotMatch	403	Sender	The signature does not match the request
InvalidClientTokenId	403	Sender	The access key id is unknown or inactive
MissingAuthenticationToken	403	Sender	The request was not signed
RequestExpired	400	Sender	The timestamp is outside the permitted skew
AccessDenied	403	Sender	Policy does not allow this action

AccessDenied is the outcome clients branch on most often, which is why it is first in this table rather than buried below the service-specific codes.

Service-specific

Code	Status	Type	Cause
NoSuchEntity	404	Sender	The user, group, role, policy or key does not exist
EntityAlreadyExists	409	Sender	A resource with that name already exists
DeleteConflict	409	Sender	The resource still has attachments or credentials
LimitExceeded	409	Sender	An account quota would be exceeded
MalformedPolicyDocument	400	Sender	The policy document is not valid
InvalidInput	400	Sender	A parameter value is not acceptable
UnmodifiableEntity	409	Sender	The resource cannot be changed

Throttling and server errors

Code	Status	Type	Cause	Retry
Throttling	400	Sender	Request rate exceeded	Yes, with backoff
ServiceFailure	500	Receiver	An unexpected failure on our side	Yes

Throttling is a 400 here and RequestLimitExceeded is a 503 in EC2. That inconsistency is inherited: each service matches the code and status its AWS counterpart returns, because client retry logic keys on both.

ServiceFailure is the code AWS IAM documents on every action for an unexpected error, so it is the code used here rather than a name of our own.

Policy evaluation failure

A policy that cannot be evaluated is our failure, not a denial. It returns ServiceFailure with a 500 — never AccessDenied.

The distinction matters more than it appears: reported as a denial, a customer spends a day rewriting a policy that was correct all along.

Absence versus denial

An entity in another account, or one that has never existed, returns NoSuchEntity. An entity in the caller’s own account that policy forbids returns AccessDenied. Existence is never confirmed to a caller not entitled to know it.

Deletion conflicts

DeleteConflict rather than a cascading delete is deliberate. Deleting a user must not silently delete the access keys something is still authenticating with: the caller is told what remains and deletes it explicitly.

Go further

• IAM requests and responses
• Actions
• IAM troubleshooting