Errors, Idempotency, and Retries

Errors use application/problem+json.

Example:

{
  "type": "https://subnano.me/problems/validation",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more fields are invalid",
  "errors": [{ "field": "primaryCategoryId", "code": "required" }]
}

Common status codes

• 400 bad request (invalid headers/body)
• 401 missing or invalid key
• 403 key not allowed for this action
• 404 endpoint/post not found
• 409 idempotency request still in flight
• 413 uploaded file too large
• 422 validation failed or idempotency payload mismatch
• 429 rate limit exceeded
• 5xx transient server errors

Idempotency behavior

Idempotency applies to:

• POST /api/v1/posts/:id/publish

For the (api key, Idempotency-Key) tuple:

• First request claims and processes.
• Replay with same payload returns stored response.
• Replay with changed payload returns 422.
• Replay while first request is processing returns 409.
• Calling publish for an already-published post returns 200 with publishResult: "no_op_already_published" and stateChanged: false.
• Retention window: 24 hours.

Retry guidance

• Retry transient failures with exponential backoff.
• Reuse the same Idempotency-Key for retries of the exact same publish request.
• Generate a new Idempotency-Key when request payload changes.
• For 409, wait and retry.
• For 422, fix payload before retrying.