Error Handling API

All Cryptid API errors follow a consistent format with standard HTTP status codes, machine-readable error codes, and optional retry guidance. This enables clients to implement robust error handling and recovery strategies.

Error Response Format

{
    "error": "ERROR_CODE",
    "message": "Human readable error description",
    "code": 4001,
    "retry_after": 300
}

Fields:

• error: Machine-readable error code (uppercase snake_case)

  • Used for programmatic error handling

• message: Human-readable error description

  • Suitable for logging or development debugging
  • Should NOT be displayed directly to end users

• code: Numeric error code (4 digits)

  • First digit matches HTTP status category (4xxx for client errors, 5xxx for server errors)
  • Unique identifier for specific error types

• retry_after (optional): Seconds to wait before retrying

  • Only present for retryable errors (rate limits, temporary failures)
  • Clients SHOULD respect this value

HTTP Status Codes

Status	Description	Retryable?
200	OK - Request successful	N/A
202	Accepted - Message queued	N/A
400	Bad Request - Invalid format	No
401	Unauthorized - Invalid token	No*
404	Not Found - Resource missing	No
413	Payload Too Large - Message too big	No
429	Too Many Requests - Rate limited	Yes
500	Internal Server Error	Yes
502	Bad Gateway - Federation failed	Yes
503	Service Unavailable	Yes

Caution

401 errors are not retryable unless you refresh the access token first.

Error Codes

Code	Error	HTTP Status	Description
4001	INVALID_SIGNATURE	400	Ed25519 signature verification failed
4002	DEVICE_NOT_ANNOUNCED	401	Device not registered for delivery
4003	MESSAGE_TOO_LARGE	413	Message exceeds server size limit
4004	RATE_LIMIT_EXCEEDED	429	Too many requests
4005	INVALID_ADDRESS	400	Malformed device address
4006	FEDERATION_FAILED	502	Cross-server delivery failed
4007	SERVER_UNREACHABLE	502/404	Target server unavailable or not found
4008	INVALID_REFRESH_TOKEN	401	Refresh token is invalid or expired
4009	INVALID_ADMIN	401	Device is not configured as admin
4010	CHALLENGE_EXPIRED	410	Admin auth challenge has expired
4011	INSUFFICIENT_PERMISSIONS	403	Admin lacks required permission
4012	INVALID_CONFIG	400	Configuration value invalid
4013	DEVICE_NOT_FOUND	404	Device not found on server
5003	FEDERATION_DISABLED	503	Recipient’s server doesn’t support federation

Error Handling Strategies

Client Errors (4xx)

Client errors indicate problems with the request that cannot be resolved by retrying without modification.

Examples:

• 4001 (INVALID_SIGNATURE): Re-sign the request with the correct device key
• 4002 (DEVICE_NOT_ANNOUNCED): Re-announce device before retrying
• 4003 (MESSAGE_TOO_LARGE): Reduce message size or split into chunks
• 4005 (INVALID_ADDRESS): Fix address format
• 4008 (INVALID_REFRESH_TOKEN): Obtain new token via /v1/announce

Server Errors (5xx)

Server errors indicate temporary issues that may be resolved by retrying with exponential backoff.

Examples:

• 4006 (FEDERATION_FAILED): Retry with backoff, store locally if persistent
• 4007 (SERVER_UNREACHABLE): Retry with backoff, notify user of delay
• 5003 (FEDERATION_DISABLED): Cannot be resolved by retry - inform user

Rate Limiting

Rate Limit Headers

All responses (success or failure) include rate limiting information:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1759000000
Retry-After: 60

Headers:

• X-RateLimit-Limit: Maximum requests allowed in the current window

• X-RateLimit-Remaining: Requests remaining in the current window

• X-RateLimit-Reset: Unix timestamp when the rate limit resets

• Retry-After: Time in seconds after which requests can be retried

Best Practices

1. Exponential Backoff: For retryable errors (5xx, 429), use exponential backoff

2. Respect Retry-After: Always respect the retry_after field

3. User-Facing Error Messages: Don’t show API error messages directly to users. Show them useful information

4. Logging and Monitoring: Log all errors with context for debugging

5. Graceful Degradation: Handle errors gracefully without blocking user experience.

Important Notes

Error Code Stability

Error codes are stable across API versions. Clients can rely on specific codes for error handling logic.

Adding New Error Codes

Future versions may add new error codes. Clients should handle unknown codes gracefully.

No Stack Traces

Error responses never include stack traces or internal server details. This prevents information leakage while maintaining debuggability through logs on the server side.