Errors

Solenoid Key returns structured error responses with machine-readable codes.

{
  "error": "Human readable message",
  "code": "service.error_name",
  "fields": { "field_name": ["Validation error message"] }
}

The fields object appears only for validation errors.

HTTP status codes

Status	Meaning
200	Success
201	Key created
400	Validation failed
401	Missing or invalid token
403	Authenticated but not authorized
404	Key not found
409	Duplicate key configuration
429	Rate limit exceeded
500	Internal server error

Returned in VerifyResult.error when valid: false.

Error	Cause	Fix
`invalid_key`	Format invalid, checksum mismatch, or not found	Check key was copied completely with no extra whitespace
`expired`	Key past its `expires_at` timestamp	Rotate to generate a new key
`revoked`	Key revoked via DELETE endpoint	Create a new key
`deleted`	Key or project soft-deleted	Contact support within 30-day retention window

Code	Status	Cause	Fix
`validation_error`	400	Request body doesn’t match schema	Check `fields` object for specifics
`invalid_prefix`	400	Prefix empty, >20 chars, or invalid characters	Use 1-20 alphanumeric chars + underscore
`duplicate_key`	409	Key with same configuration exists	Change `name` or use existing key

Shared across all Solenoid services.

Code	Cause	Fix
`invalid_request`	Malformed JSON or wrong Content-Type	Validate request format
`unauthorized`	Missing or invalid authentication	Check Bearer token
`forbidden`	Not authorized for this resource	Verify project access
`not_found`	Resource doesn’t exist	Check key ID
`rate_limit_exceeded`	Too many requests	Implement backoff. See Rate Limits.
`internal_error`	Server error	Report to support

Code	Cause	Fix
`key.invalid_key`	Key format invalid or not found	Verify key format: `prefix_entropy_checksum`
`key.expired`	Key past expiration	Rotate to get a new key
`key.revoked`	Key explicitly revoked	Create a new key
`key.deleted`	Key soft-deleted	Contact support within 30 days
`key.invalid_prefix`	Prefix validation failed	Use 1-20 alphanumeric + underscore chars