Skip to main content
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"
  }
}
StatusMeaningCommon cause
400The request is malformed or semantically invalid.Invalid status filter, deployment payload, agreement JSON, or signed input payload.
401Missing, invalid, or unsupported API credential.X-API-Key is absent, revoked, disabled, or incorrect; Authorization: Bearer cns_pk_... is accepted only as an API-key alias.
402The authenticated API principal has paid_required entitlement mode for the requested scope.Per-call x402 settlement is not implemented. Treat this as an entitlement/operator issue.
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.
429Rate 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.
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?.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:
  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 ID or deployed address points to the intended record
  2. the API key can access that record
  3. the requested operation is valid for the agreement’s current lifecycle position
  4. the current state still accepts the action you are submitting
  5. the signing wallet is authorized for the requested action