Error Codes

ASP defines a structured set of rejection codes and error categories. These codes appear in REJECT message bodies (via the code field) and in INFORM messages with informType: "error". Implementations SHOULD use these codes to enable programmatic error handling and automated recovery.

Rejection Code Registry

Code	Category	Description	Retryable	Recommended Recovery
`insufficient_trust_score`	Trust	Sender's trust score is below the recipient's threshold	No	Build trust through successful sessions over time
`unauthorized`	Auth	Sender lacks required permissions or credentials	No	Verify credentials, scopes, and DPoP proof
`schema_unsupported`	Protocol	Proposed schema or format is not supported by the recipient	No	Use a schema the recipient's Agent Card declares as supported
`budget_exceeded`	Economic	Proposed terms exceed the recipient's budget or ceiling	Yes	Reduce the requested amount or adjust terms
`capacity_unavailable`	Resource	Requested resources are not currently available	Yes	Retry after a delay or adjust resource requirements
`policy_violation`	Governance	Request violates the recipient's organizational policy	No	Review the recipient's published policies
`timeout`	Temporal	Response window for the referenced message has expired	Yes	Send a new proposal with a longer timeout
`duplicate`	Protocol	A message with this identifier has already been processed	No	Use a new `proposalId` or `commitmentId`
`escalation_required`	Authority	Request requires human approval or higher authority	Yes	Wait for escalation to resolve, then retry
`unspecified`	General	No specific machine-readable reason applies	Varies	Check the `reason` field for a human-readable explanation

The insufficient_trust_score rejection is not immediately retryable, but the underlying condition can improve over time. Trust scores increase through successful sessions, so agents with low scores can eventually meet higher thresholds.

Error Categories

Protocol Errors

Violations of the ASP specification itself. These errors indicate a bug in the sender's implementation.

Error	Description
Invalid state transition	Performative is not valid for the current session state (e.g., COMMIT from IDLE)
Malformed message	Required fields are missing or have invalid types
Schema violation	Message body does not match the performative's defined schema
Hash chain failure	`integrity.hash` does not match content, or `previousHash` is incorrect
Duplicate message ID	A message with this `messageId` has already been processed
Version mismatch	`version` field does not match a supported protocol version

Trust Errors

Errors related to the trust scoring system.

Error	Description
Insufficient trust score	Sender's composite score is below the recipient's minimum threshold
Trust ceiling exceeded	Transaction value exceeds the maximum allowed for the sender's trust level
Trust not established	New agent with no session history (trust score is 0)

Economic Errors

Errors related to budgets, escrow, and financial terms.

Error	Description
Budget exceeded	Proposed amount is higher than the recipient's configured budget
Escrow insufficient	Commitment requires escrow but the deposited amount is not enough
Transaction ceiling reached	Trust-level-based limit on maximum transaction value has been hit

Temporal Errors

Errors caused by timing issues.

Error	Description
Response timeout	`maxResponseTimeMs` constraint expired before a response was received
Proposal expired	`validUntil` timestamp has passed
Session timeout	Total session lifetime has exceeded the configured maximum
Escalation timeout	Escalation did not receive resolution within the timeout period

Auth Errors

Errors related to authentication and authorization.

Error	Description
Invalid DPoP proof	DPoP JWT is malformed, expired, or does not match the request
Unauthorized	Access token is missing, expired, or invalid
Scope mismatch	Access token does not include the required scope for this operation

Transport Errors

Errors at the delivery layer, below the protocol level. These are not part of the ASP message format but may be returned by the transport binding.

Error	Description
Delivery failure	Target agent's endpoint is unreachable
Instance unavailable	Target instance is down or unreachable
Rate limit exceeded	Too many messages in the current rate window

Using Error Codes in Messages

REJECT with Error Code

When rejecting a proposal or commitment, include the rejection code in the content.body:

{
  "version": "asp/0.1",
  "messageId": "019526a1-8f2a-7000-8000-000000000005",
  "sessionId": "019526a1-7c3e-7000-8000-000000000001",
  "sequenceNumber": 4,
  "timestamp": "2026-03-07T14:35:00.000Z",
  "sender": {
    "agentId": "agent://cloudprime.io/gpu/beta",
    "orgId": "org_cloudprime",
    "trustScore": 91,
    "dpopProof": "eyJ..."
  },
  "performative": "REJECT",
  "content": {
    "mimeType": "application/asp+json",
    "body": {
      "referenceId": "prop_001",                          // ← ID of the rejected proposal
      "reason": "Requested price is below our minimum",   // ← Human-readable
      "code": "budget_exceeded",                           // ← Machine-readable
      "retryable": true                                    // ← Sender MAY retry with new terms
    }
  },
  "integrity": {
    "hash": "sha256:a1b2c3d4...",
    "previousHash": "sha256:e5f6a7b8...",
    "signature": "ed25519:x1y2z3..."
  }
}

The retryable: true flag tells the sender that a modified proposal with different terms could succeed. Implementations SHOULD respect this flag when deciding whether to retry.

INFORM with Error Type

When reporting an error during execution (not a rejection of a proposal), use INFORM with informType: "error":

{
  "version": "asp/0.1",
  "messageId": "019526a1-9a1b-7000-8000-000000000008",
  "sessionId": "019526a1-7c3e-7000-8000-000000000001",
  "sequenceNumber": 7,
  "timestamp": "2026-03-07T14:40:00.000Z",
  "sender": {
    "agentId": "agent://cloudprime.io/gpu/beta",
    "orgId": "org_cloudprime",
    "trustScore": 91,
    "dpopProof": "eyJ..."
  },
  "performative": "INFORM",
  "content": {
    "mimeType": "application/asp+json",
    "body": {
      "informType": "error",                            // ← Error, not rejection
      "subject": "GPU provisioning failed",
      "data": {
        "error": "Resource provisioning timed out",
        "commitmentId": "cmt_001",                      // ← Which commitment is affected
        "retryable": true,                               // ← Can be retried
        "suggestedAction": "Retry in 5 minutes"
      }
    }
  },
  "integrity": {
    "hash": "sha256:b2c3d4e5...",
    "previousHash": "sha256:f6a7b8c9...",
    "signature": "ed25519:z3a4b5..."
  }
}

An INFORM error during the EXECUTING state does not automatically end the session. The parties MAY negotiate a resolution, retry, or ESCALATE. Only an explicit CLOSE or a timeout transitions the session to a terminal state.

Handling Unknown Codes

If an implementation receives a rejection code it does not recognize:

Treat the error as unspecified
Read the reason field for a human-readable explanation
Check the retryable field to determine if a retry is appropriate
Log the unknown code for monitoring and future reference

Implementations MUST NOT reject a message solely because it contains an unknown rejection code. The registry MAY be extended in future protocol versions.

Error Decision Flow

  Receive error response
       │
       ├── Has "code" field?
       │      │
       │      ├── Yes ──► Look up code in registry
       │      │              │
       │      │              ├── Known code ──► Handle per recovery action
       │      │              │
       │      │              └── Unknown code ──► Treat as "unspecified"
       │      │
       │      └── No ──► Read "reason" field for human-readable explanation
       │
       └── Check "retryable" field
              │
              ├── true ──► Modify request and retry (with backoff)
              │
              ├── false ──► Do not retry. Adjust approach or ESCALATE.
              │
              └── absent ──► Assume not retryable unless context suggests otherwise

State Machine

How errors and rejections affect session state transitions.

Security Model

Auth errors, DPoP validation, and cryptographic integrity checks.

Was this page helpful?

Error Codes

State Machine

Security Model

On this page