Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.shodai.network/llms.txt

Use this file to discover all available pages before exploring further.

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

​
HTTP status codes

StatusMeaningCommon cause
400The request is malformed or semantically invalid.Invalid status filter, deployment payload, agreement JSON, or signed input payload.
401Missing or invalid API key.X-API-Key is absent, revoked, disabled, or incorrect.
402Payment required for the requested scope.The principal has a paid_required entitlement mode for the requested scope.
403Authenticated but not allowed.Missing active entitlement, blocked entitlement, or resource access denial.
404Requested agreement or resource was not found.Wrong agreement ID, wrong deployed address, or unavailable record.
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.
StatusWhere it may surfaceCommon causeNext check
409Deployment 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 '@cns-labs/agreements-api-client';

try {
  await client.validateDeployment(payload);
} catch (error) {
  if (error instanceof AgreementsApiError) {
    console.error({
      status: error.status,
      message: error.errorPayload?.message,
      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.

​
Input does not move the agreement

Check these conditions in order:
  1. The agreement is in the state that accepts the input.
  2. The submitted inputId exists in the authored agreement.
  3. The submitted values match the input schema.
  4. The signer is allowed by the input issuer.
  5. The transition condition references that input from the current state.
  6. The signature has not expired and was generated for this exact payload.
If an input record is MINED but state has not updated yet, reread GET /v0/agreements/{id}/state after a short delay and use GET /v0/agreements/{id}/inputs as the audit trail.

​
Deployment conflicts

For deployment and operation failures, confirm that:
  1. the agreement has the expected Draft or Deployed status
  2. the requested operation is valid for that status
  3. the agreement ID or deployed address points to the intended record
  4. the API key can access that record
  5. the current state still accepts the action you are submitting