Errors and troubleshooting

Use this page when an API request fails or when an agreement does not move through the lifecycle as expected.

HTTP status codes

Error responses use a top-level error object. Use error.requestId when sharing a failure with support.

{
  "error": {
    "code": "bad_request",
    "message": "limit must be an integer between 1 and 100",
    "details": {
      "field": "limit"
    },
    "requestId": "req_123"
  }
}

Status	Meaning	Common cause
`400`	The request is malformed or semantically invalid.	Invalid status filter, deployment payload, agreement JSON, or signed input payload.
`401`	Missing, invalid, expired, or unsupported API credential.	The API key is absent, revoked, disabled, or for another environment; or the OAuth access token is expired, invalid, or issued by the wrong environment. See Authentication.
`402`	The authenticated Shodai account has `paid_required` entitlement mode for the requested scope.	Per-call x402 settlement is not implemented. Treat this as an entitlement/operator issue.
`403`	Authenticated but not allowed.	Missing active entitlement, blocked entitlement, or resource access denial.
`404`	Requested agreement or resource was not found.	Wrong agreement ID, wrong deployed address, or unavailable record.
`429`	Rate limited.	Too many requests in a short window; back off before retrying.

Use the API Reference group in the sidebar for endpoint-specific response schemas.

Downstream conflict responses

Some deployment or input operations may surface 409 Conflict from the downstream agreements service. This note is separate from the main status table; use the API Reference group for generated endpoint-specific response codes.

Status	Where it may surface	Common cause	Next check
`409`	Deployment or input operations.	The record is in the wrong lifecycle status for the operation, or the live state no longer accepts the submitted action.	Reread the agreement record and current state, then confirm the requested operation is valid for that status and state.

Validate the right thing

POST /v0/agreements/validate-template checks authored agreement JSON only. If it fails or returns warnings, inspect participant variable keys, input IDs, state IDs, and agreement structure before preparing deployment. POST /v0/agreements/validate checks the assembled deployment request. If it fails, compare the authored agreement with initValues, participant wallet mappings, observers, and the normalized variables response.

Deployment preflight does not deploy the agreement and does not validate permit signatures.

Fix signing failures

Regenerate the signature if any of these values change:

agreement JSON
initValues
docUri
chain
factory or agreement address
signer nonce
deadline
input ID
input values

For deployment, sign the effective post-mapping values returned by POST /v0/agreements/validate, not raw caller input, when participant mappings change values included in the signature.

The TypeScript client uses a one-hour default permit lifetime through computeDefaultDeadlineSeconds(). Use a shorter deadline if your integration requires a tighter replay window, and regenerate the signature whenever the deadline expires.

Diagnose errors in the TypeScript client

ApiClient throws AgreementsApiError for unexpected HTTP responses. Inspect status, errorPayload, bodyText, and parsedBody before retrying.

import { AgreementsApiError } from '@shodai-network/agreements-api-client';

try {
  await client.validateDeployment(payload);
} catch (error) {
  if (error instanceof AgreementsApiError) {
    console.error({
      status: error.status,
      message: error.errorPayload?.error.message,
      code: error.errorPayload?.error.code,
      requestId: error.errorPayload?.error.requestId,
      body: error.parsedBody,
    });
  }
  throw error;
}

Use client.exchangeJson('GET', '/v0/agreements') when you need status, ok, headers, bodyText, and parsedBody without throwing on HTTP errors. For successful raw HTTP responses, inspect data first. List responses also include pageInfo; single-resource responses include only data and meta.

Input does not move the agreement

Check these conditions in order:

The agreement is in the state that accepts the input.
The submitted inputId exists in the authored agreement.
The submitted values match the input schema.
The signer is allowed by the input issuer.
The transition condition references that input from the current state.
The signature has not expired and was generated for this exact payload.

If an input record is PENDING and state has not updated yet, the transaction has been submitted but is not yet finalized on chain; state advances when the input becomes FINALIZED. Reread GET /v0/agreements/{id}/state after a short delay, subscribe to agreement.transitioned to be told when it happens, and use GET /v0/agreements/{id}/inputs as the audit trail.

Deployment conflicts

For deployment and operation failures, confirm that:

the agreement ID or deployed address points to the intended record
the authenticated Shodai account can access that record
the requested operation is valid for the agreement’s current lifecycle position
the current state still accepts the action you are submitting
the signing wallet is authorized for the requested action

Start

Workflow

Webhooks

Architecture

Examples

Reference

HTTP status codes

Downstream conflict responses

Validate the right thing

Fix signing failures

Diagnose errors in the TypeScript client

Input does not move the agreement

Deployment conflicts

​HTTP status codes

​Downstream conflict responses

​Validate the right thing

​Fix signing failures

​Diagnose errors in the TypeScript client

​Input does not move the agreement

​Deployment conflicts

​Related pages

HTTP status codes

Downstream conflict responses

Validate the right thing

Fix signing failures

Diagnose errors in the TypeScript client

Input does not move the agreement

Deployment conflicts

Related pages