Error Code Catalogue¶

Purpose¶

The Error Code Catalogue defines the standard machine-readable error codes used by future Algosure API contracts.

Standard Error Categories¶

Code	Category	Meaning
`VALIDATION_FAILED`	Validation	Request shape or field values are invalid.
`BUSINESS_RULE_VIOLATION`	Domain	Owning Domain rejected the command under business rules.
`RESOURCE_NOT_FOUND`	Query	Resource was not found or is not visible to the caller.
`RESOURCE_CONFLICT`	Conflict	Request conflicts with current resource or workflow state.
`AUTHENTICATION_REQUIRED`	Authentication	No valid authenticated caller was established.
`TOKEN_INVALID`	Authentication	Token is invalid, expired, malformed, or not trusted.
`AUTHORIZATION_DENIED`	Authorization	Caller lacks required role, permission, policy, or ownership.
`MFA_REQUIRED`	Authorization	Step-up authentication is required before action.
`TENANT_CONTEXT_REQUIRED`	Tenant	Tenant context is missing.
`ORGANIZATION_CONTEXT_REQUIRED`	Tenant	OrganizationId is missing for organization-scoped API.
`TENANT_ACCESS_DENIED`	Tenant	Caller cannot access the requested tenant or organization.
`ENTITLEMENT_REQUIRED`	Billing	Subscription plan or entitlement does not allow the action.
`USAGE_LIMIT_REACHED`	Billing	Billing-owned usage limit has been reached.
`IDEMPOTENCY_KEY_REQUIRED`	Idempotency	Retryable unsafe command requires idempotency key.
`IDEMPOTENCY_CONFLICT`	Idempotency	Same key was reused with different command intent.
`RATE_LIMIT_EXCEEDED`	Rate limit	Caller exceeded allowed request rate.
`QUOTA_EXCEEDED`	Rate or plan	Caller exceeded operational or plan quota.
`INTEGRATION_UNAVAILABLE`	Integration	External dependency is unavailable or timed out.
`INTEGRATION_CALLBACK_INVALID`	Integration	Callback signature, source, or payload is invalid.
`INTERNAL_ERROR`	Internal	Unexpected failure that must not expose internals.

Error Mapping Principles¶

Use the most specific stable code available.
Domain-specific codes may extend this catalogue later under owning Domain control.
Authentication, authorization, tenant, entitlement, idempotency, and rate limit errors must be distinguishable.
RESOURCE_NOT_FOUND may be used instead of AUTHORIZATION_DENIED when revealing existence would leak information.

Error Decision Flow¶

flowchart TD
    Request[Request]
    Authn[Authentication]
    Tenant[Tenant Context]
    Authz[Authorization]
    Entitlement[Entitlement]
    Validation[Validation]
    Domain[Domain Rules]
    Error[Standard Error Code]

    Request --> Authn
    Authn -->|fail| Error
    Authn --> Tenant
    Tenant -->|fail| Error
    Tenant --> Authz
    Authz -->|fail| Error
    Authz --> Entitlement
    Entitlement -->|fail| Error
    Entitlement --> Validation
    Validation -->|fail| Error
    Validation --> Domain
    Domain -->|fail| Error