Idempotency

The SurfacedBy API supports idempotency keys on write endpoints so you can retry safely after a network error without creating duplicate resources.

Header

Send a unique key in the Idempotency-Key header on every write request:

curl -X POST https://api.surfacedby.com/api/v1/ext/domains \
  -H "X-API-Key: sk_live_..." \
  -H "Idempotency-Key: 9f8e2b1a-0c4d-4a7e-8b3f-5d1e2a3c6d7f" \
  -H "Content-Type: application/json" \
  -d '{"domain": "yourbrand.com"}'

Generate a fresh UUID (or any unique token up to 255 characters) per logical operation. Reusing the same key for a different operation produces an error.

Scope

Idempotency keys are scoped to the API key that sent them. Two different API keys can use the same idempotency key without conflict. A single API key that sends the same idempotency key twice will replay the first response.

Replay window

Keys are retained for 24 hours. Sending the same key again within the window returns the stored response exactly as it was returned the first time, including the original status code, headers, and body. After the window expires, the key can be used again for a new operation.

In-progress collision

If a retry arrives while the original request is still in flight, the API returns a 409 response indicating the key is currently in use. Wait for the original request to complete (or time out) and retry then.

When to use it

Use idempotency keys on every mutating request: POST, PUT, PATCH, DELETE. Even on endpoints that look safe to retry without one, the key protects you from edge cases where a 5xx or network failure makes it impossible to tell whether the server processed the request.

On read endpoints (GET) idempotency keys are unnecessary and are ignored.

Errors

• 409 conflict - the key is currently in use by an in-flight request.
• 422 validation_error - the key was previously used with a different request body. Pick a fresh key.

See Errors for the full error catalogue.