Edit

Microsoft agent identity platform error codes

This article explains Microsoft Graph errors for agent identity objects. OAuth sign-in failures and local tooling failures use different diagnostics; use the routes below before changing a directory object or its permissions.

Identify the failing layer

Failure Start here
Local browser, WAM, or missing Microsoft Graph sign-in context. Management-client sign-in. An empty Get-MgContext isn't successful authentication.
OAuth response containing AADSTS or token acquisition failure. Microsoft identity platform error codes. Confirm tenant, client ID, audience, and the scenario's required consent.
Microsoft Graph HTTP error while provisioning or updating objects. The tables in this article and Microsoft Graph error responses.
API returns 401 or 403 after a token is acquired. Your API's token validation and authorization requirements. A token request succeeding doesn't prove that its audience, scopes, roles, or resource access match the API operation.

For a failed Graph request, retain the HTTP status, error.code, error.message, request timestamp, and request-id response header. Record which operation and tenant failed, but don't include tokens, secrets, or private keys in support requests. Distinguish the object and client IDs before retrying. Don't treat every 403 as a propagation delay or grant broader permissions without diagnosing the denial.

Handling error codes in your application

The OAuth2.0 spec provides guidance on how to handle errors during authentication using the error portion of the error response. For more information on handling error code and the possible error field values, see the Microsoft identity platform and OAuth 2.0 error codes documentation.

Quota and limit errors

These errors occur when you exceed the tenant quota or the maximum number of agent identity blueprints or agent identities.

Error code Description
Agent_Directory_QuotaExceeded Agent identity blueprints or agent identities have reached their resource quota (80% of the tenant's overall resource quota by default). This error also occurs when total directory object usage reaches the separate creation threshold (95% by default). To create more, reduce the relevant usage or request a higher directory object quota.
AgentBlueprint_LimitExceeded You've reached the maximum number of agent identity blueprints allowed including active and soft-deleted items. To create more, you must permanently delete unneeded blueprints.
AgentIdentity_LimitExceeded You've reached the maximum number of agent identities allowed including active and soft-deleted entries. To add more, you must permanently delete unneeded agent identities.

Agent identity blueprint errors

These errors occur when a request includes properties or API versions that agent identity blueprints don't support.

Error code Description
AgentBlueprint_IncompatibleProperty A property specified in the request is incompatible with agent identity blueprints and can't be set.
AgentBlueprint_IncompatibleProperty_NullPropertyName A property in the request is incompatible with agent identity blueprints and can't be set.
AgentBlueprint_NotSupportedOnApiVersion Agent identity blueprints aren't supported on the API version used in this request.

Agent identity blueprint principal errors

These errors occur when a request includes properties, API versions, or parent resources that agent identity blueprint principals don't support.

Error code Description
AgentBlueprintPrincipal_AgentIdentity_IncompatibleProperty A property specified in the request is incompatible with agent identity and can't be set.
AgentBlueprintPrincipal_IncompatibleProperty A property specified in the request is incompatible with agent identity blueprint principals and can't be set.
AgentBlueprintPrincipal_NotSupportedOnApiVersion Agent identity blueprint principals aren't supported on the API version used in this request.
AgentBlueprintPrincipal_RequireAgentBlueprint Agent identity blueprint principals can only be created for Agent Blueprints.

Agent identity errors

These errors occur when a request references a missing blueprint principal, an incompatible parent type, or unsupported credentials or API versions for agent identities.

Error code Description
AgentIdentity_AgentBlueprintPrincipalDoesNotExist For a fleet, create the blueprint principal and check that its appId matches the blueprint. For a single-instance agent, don't create a principal; use the single-instance provisioning request, which references the blueprint object ID.
AgentIdentity_CredentialsNotSupported Credentials are not supported for agent identities. All credentials must be added to the agent identity blueprint.
AgentIdentity_IncompatibleParentType The specified Application (AppId) isn't an Agent Blueprint. The AgentIdentityBlueprintId must be set to the AppId of a valid agent identity blueprint.
AgentIdentity_NotSupportedOnApiVersion Agent identities aren't supported on the API version used in this request.

Agent identity creation errors

These errors occur when the calling principal isn't allowed to create the requested agent identity.

Error code Description
Error_AgentBlueprintCannotCreateAssociatedIdentity Agent identity blueprints can't create agent identities that are associated with another agent identity blueprint. To create this agent identity, either use the agent identity blueprint that's associated with the agent identity, or perform the operation with a different principal that has the required roles/permissions to create agent identities.
Error_AgentIdentitiesCreatingAgentIdentitiesNotAllowed Agent identities can't create other agent identities. To create an agent identity, use the associated agent identity blueprint principal or nonagent blueprint service principal with the required permissions.
Error_AgentIdentitySelfCreateRequired Applications can only create agent identities under themselves. The provided AgentIdentityBlueprintId doesn't match the calling application's AppId.

Get help

If you have a question or can't find what you're looking for, see Support and help options for developers to learn about other ways you can get help.