Error Codes
Understanding and handling errors
/
Error Format
All errors follow a consistent format:
JSON
{
"error": "auth_required",
"message": "Authentication required",
"auth_method": "none"
}
Authentication Errors
| Code | Description | Solution |
|---|---|---|
auth_required |
No valid auth proof provided | Provide X-Lemma-Credential, access token, agent token, or API key |
missing_lemma_header |
X-Lemma-Credential missing |
Send base64url(JSON) signed credential header |
invalid_lemma_header |
Credential header could not be decoded | Verify base64url encoding and JSON payload shape |
invalid_lemma:untrusted_issuer |
Issuer not in trust set | Add/align issuer DID in trusted issuer config |
Credential Errors
| Code | Description | Solution |
|---|---|---|
invalid_lemma:invalid_signature |
Credential signature invalid | Ensure signed fields are preserved and not rewritten client-side |
invalid_lemma:expired |
Credential has expired | Request new credential |
credential_revoked |
Credential was revoked | Request new credential |
credential_id_mismatch |
X-Credential-ID does not match credential payload id |
Send matching credential id or omit optional header |
API Errors
| Code | HTTP | Description |
|---|---|---|
Invalid API key |
401 | API key invalid or missing |
RATE_LIMITED |
429 | Too many requests |
missing_scope |
403 | Credential/token lacks required scope |
invalid_access_token |
401 | Malformed, expired, or incompatible access token |
SERVER_ERROR |
500 | Internal server error |