Troubleshooting

My API key returns invalid_key

Is the key format correct? Keys follow the pattern prefix_entropy_checksum and are 50+ characters.

Was the key copied completely? Check for truncation or extra whitespace. Trim the value before use:

const apiKey = headers.get('Authorization')?.replace('Bearer ', '').trim()

Was the key revoked or deleted? List your keys and check the revoked_at field:

curl https://api.solenoid.systems/v1/keys \
  -H "Authorization: Bearer YOUR_TOKEN"

If revoked, create a new key. Revoked keys cannot be restored.

Rotated key stopped working before grace period ended

Wait a few seconds and retry. Rotation invalidates caches immediately, but propagation to all edge nodes may take a moment.

Check the key’s expires_at to confirm the grace period matches your expectation:

curl https://api.solenoid.systems/v1/keys/:old_key_id \
  -H "Authorization: Bearer YOUR_TOKEN"

Grace period defaults to 24 hours but may differ if a custom grace_hours value was passed during rotation. The old key expires at rotation_time + grace_hours.

Verification is slow (>10ms)

First request after key creation or rotation is always slower. This is normal — it includes bcrypt and a database call (~10-20ms). Subsequent requests hit the KV cache (<1ms).

Pre-warm the cache by verifying the key once immediately after creation.

Use RPC binding instead of HTTP for lower latency on service-to-service calls.

Check edge proximity. Look at the CF-Ray header to confirm which Cloudflare edge PoP is handling requests.

Need to immediately invalidate a key

Revoke the key:

curl -X DELETE https://api.solenoid.systems/v1/keys/:key_id \
  -H "Authorization: Bearer YOUR_TOKEN"

Revocation propagates to all cache layers within ~2 seconds. All future verifications return error: 'revoked'. The key is soft-deleted with 30-day retention.

Use rotation instead if you need a grace period for deployment.

Key creation returns 409 Conflict

A key with the same prefix + name + scopes configuration already exists. List keys to find the duplicate:

curl https://api.solenoid.systems/v1/keys \
  -H "Authorization: Bearer YOUR_TOKEN"

Change the name field (names must be unique per project), use the existing key, or delete the old one first.

Next steps