REST API Patterns

Use these patterns across Mimic integrations to reduce incidents and retry bugs.

Idempotency

• Attach an idempotency key to mutating requests.
• Keep dedupe windows long enough for client retry behavior.
• Return prior successful responses when duplicate keys are received.

Error shape

Use a stable contract:

{
  "error": "invalid_payload",
  "message": "workflowId is required",
  "requestId": "req_123"
}

Include machine-readable error and human-readable message.

Pagination

For list endpoints, use cursor pagination:

• limit to control page size
• cursor to request next page
• response includes nextCursor

Backoff and retries

• Retry 429 and 5xx with exponential backoff.
• Do not retry 4xx validation or permission errors.
• Keep request timeouts explicit in client config.

Observability

• Propagate a request ID from caller to downstream services.
• Log latency, status, and error code for every API call.
• Track webhook lag and callback failure counts as first-class metrics.