Error Codes
All DID.comms errors return a JSON body with an error string and, where applicable, a machine-readable code.
Error Response Format
{
"error": "Raw DIDs are not accepted. Use a recipient API key or handle.",
"code": "RAW_DID_REJECTED"
}Complete Error Reference
| HTTP Status | Error Code | Description | Troubleshooting |
|---|---|---|---|
| 200 | — | Success. Envelope delivered or request completed. | — |
| 400 | MISSING_FIELD | A required field is missing from the request body. | Check your request body against the schema. |
| 400 | RAW_DID_REJECTED | Raw DIDs are not accepted. Use a recipient API key or handle. | Check your request body against the schema. |
| 401 | UNAUTHORIZED | Missing or invalid authentication credentials. | Verify your Authorization header and token. |
| 403 | KEY_INACTIVE | The API key has been revoked or deactivated. | Check the key status in your dashboard. |
| 403 | GOVERNANCE_BLOCKED | Governance enforcement prevented execution. Check council action status or partner suspension state. | Review council actions in the governance portal. |
| 404 | KEY_NOT_FOUND | The specified API key does not exist. | Verify the api_key_id is correct. |
| 405 | METHOD_NOT_ALLOWED | Only POST is accepted on /send. | Use POST method only. |
| 422 | BADGE_DENIED_DRIFT | Badge issuance denied — drift exceeds hard limit (0.30). Signal is too unstable for any badge tier. | Review the purity thresholds in the Purity Thresholds reference. |
| 422 | BADGE_DENIED_THRESHOLDS | Badge issuance denied — one or more purity thresholds not met (clarity ≥ 0.75, coherence ≥ 0.70, confidence ≥ 0.90, drift ≤ 0.10). | Review the purity thresholds in the Purity Thresholds reference. |
| 422 | COMPLIANCE_CIRCUIT_FAILED | Compliance circuit validation failed. Check the circuit-specific requirements for your jurisdiction. | Review the purity thresholds in the Purity Thresholds reference. |
| 429 | RATE_LIMIT_EXCEEDED | You have exceeded your plan's rate limit. Back off and retry. | Wait and retry, or upgrade your plan. |
| 429 | MONTHLY_LIMIT_EXCEEDED | You have exhausted your monthly message allowance. Upgrade your plan. | Wait and retry, or upgrade your plan. |
| 500 | INTERNAL_ERROR | An unexpected server error. Contact support if persistent. | Contact support. |
Retry Strategy
429Back off exponentially. The Retry-After header indicates when to retry. Consider upgrading your plan.
500Retry with exponential backoff (1s, 2s, 4s). If persistent after 3 retries, contact support.
400Do not retry — fix the request. Check the code field for the specific issue.
401/403Do not retry — verify your credentials and key status.