Witness Errors

All errors return a structured JSON response:

{
  "error": {
    "code": "error_code",
    "message": "Human readable message"
  }
}

Common errors

Code	Status	Cause	Fix
`validation_error`	400	Invalid request body or parameters	Check `fields` object for specific failures
`unauthorized`	401	Missing or invalid API key	Add `Authorization: Bearer sm_...` header. See Authentication
`forbidden`	403	Not authorized for this resource	Verify you own the chain you’re accessing
`not_found`	404	Chain or resource doesn’t exist	Check chain ID; ensure chain is initialized
`insufficient_balance`	402	Not enough balance for operation	Add credits at Pricing
`rate_limit_exceeded`	429	Too many requests	Implement exponential backoff. See Rate Limits

Code	Status	Cause	Fix
`witness.chain_not_initialized`	400	Chain not initialized	Call `POST /v1/witness/sys/init` before notarizing logs
`witness.chain_already_initialized`	409	Chain already exists	Initialization is one-time; skip init and proceed to notarize
`witness.invalid_config`	400	S3 config validation failed	Check all required fields (endpoint, bucket, region, credentials)
`witness.storage_endpoint_blocked`	400	S3 endpoint blocked by SSRF check	Use public HTTPS endpoints only; no private IPs or localhost
`witness.invalid_receipt_format`	400	Receipt missing required fields	Use complete receipt from `POST /v1/witness/log`
`witness.log_too_large`	413	JSON log exceeds size limit	Reduce log size to under 100 KB

Check status.solenoid.systems
Review the API Reference
See Troubleshooting for step-by-step diagnosis
Contact support@solenoid.systems with your chain ID, sequence ID, and error messages