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.

Creation disclosure errors

Publishing any free or paid draft without a complete author declaration returns 422:

{
  "type": "https://subnano.me/problems/validation",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more fields are invalid for publish",
  "errors": [
    {
      "field": "creationMethod",
      "code": "required",
      "message": "Select how this post was created"
    },
    {
      "field": "creationAttested",
      "code": "required",
      "message": "Confirm that you have reviewed this post and take responsibility for publishing it"
    }
  ]
}

Save the draft, add creationMethod and creationAttested: true with PATCH /api/v1/posts/:id, then retry publish with a new Idempotency-Key.

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.