Errors and idempotency

Understand error responses and make write requests safe to retry.

Read structured errors

Errors include code, message, and request_id. Use code for application logic and message for debugging. Include request_id when contacting support. Never retry authentication errors without correcting the key.

curl -X POST https://api.lumen.dev/v1/connections -H "Idempotency-Key: connect-usr_123-github" -H "Authorization: Bearer $LUMEN_API_KEY" -H "Content-Type: application/json" -d '{"provider":"github"}'

curl -X POST https://api.lumen.dev/v1/connections -H "Idempotency-Key: connect-usr_123-github" -H "Authorization: Bearer $LUMEN_API_KEY" -H "Content-Type: application/json" -d '{"provider":"github"}'

curl -X POST https://api.lumen.dev/v1/connections -H "Idempotency-Key: connect-usr_123-github" -H "Authorization: Bearer $LUMEN_API_KEY" -H "Content-Type: application/json" -d '{"provider":"github"}'

Retry writes safely

Provide an Idempotency-Key on POST requests. Lumen retains the original result for 24 hours and returns it for identical retries. Reusing a key with different parameters returns 409. Use a new key for each distinct operation.