Create short links (sync batch)
Sync batch create. Body items length 1–100. Each item requires client_ref (unique within the batch) plus destination (url XOR longUrl) and optional alias. Partial success: HTTP 200 envelope with per-item ok + result (ActiveLinkCreated | NonActiveLinkCreated) or ok: false + problem + retryable. Correlate by client_ref only — never by array index. Over 100 items → 400 BATCH_TOO_LARGE (/problems/batch-too-large). Whole-batch Idempotency-Key required (scoped as batch:{key}). Same auth / abuse / destination safety rules as single create. Missing scope → 403 INSUFFICIENT_SCOPE. Accepted credentials are anonymous access, a session cookie, or an API key with batches:create. An OAuth access token is not accepted. 批量重试只有三种情况,不要混用。示例:key 为 batch-1,两项 client_ref 分别为 notes(https://example.com/notes)和 draft(https://example.com/draft)。notes 成功,draft 的 retryable 为 true。(1) 传输结果不确定(没有拿到已完成的响应、IDEMPOTENCY_IN_PROGRESS、幂等锁不可用,或因瞬时数据库错误且一条都未创建而返回 503):用同一个 key 原样重发整批。已完成的批次返回已保存的结果,notes 不会再次创建。key 已被释放时,同一批会重新执行。(2) 已完成且某项 retryable 为 true:重放 batch-1 只返回已保存的结果,不会重试 draft。只用新 key(例如 batch-1-draft)发送 draft,并保留 client_ref draft,不要带上 notes。去掉 notes 后仍用 batch-1 会返回 IDEMPOTENCY_CONFLICT。(3) 校验错误:改正请求,不要把同一份无效请求当作网络重试。key 尚未保存的 400(重复 client_ref、缺少 items、BATCH_TOO_LARGE)改正后可以继续用同一个 key。已完成且 retryable 为 false 的项已保存;修改请求体后继续使用原 key,会返回 IDEMPOTENCY_CONFLICT,改正后的项必须用新 key。 Batch retry has three cases; do not mix them. Worked example: key batch-1 with client_ref notes (https://example.com/notes) and draft (https://example.com/draft). notes succeeds and draft is retryable true. (1) Uncertain transport outcome — no completed body, IDEMPOTENCY_IN_PROGRESS, an unavailable idempotency lock, or 503 because a transient database error created nothing: resend the entire unchanged batch with the same key. A completed batch returns the stored result and notes is not created again. A released key runs that same batch again. (2) Completed batch with retryable true: replaying batch-1 returns the stored body and does not retry draft. Send only draft, keeping client_ref draft, under a new key such as batch-1-draft. Do not include notes. Dropping notes and reusing batch-1 returns IDEMPOTENCY_CONFLICT. (3) Validation error: fix the request. Do not resend the same invalid body as a network retry. A 400 before the key is stored (duplicate client_ref, missing items, BATCH_TOO_LARGE) may reuse the key after the body is corrected. A completed item with retryable false is stored; a changed body on that key returns IDEMPOTENCY_CONFLICT, so send the corrected item with a new key.
Request
- Base URL: https://xn--s7y.xn--3ds443g
- URL: https://xn--s7y.xn--3ds443g/v1/links/batch
- Auth: one of:
- none
- HTTP bearer
- API key in cookie duan_session
Headers
Client-generated key for the whole batch. Scope = authenticated user or API key, or anonymous client id (X-Duan-Client-Id / sealed anon cookie) — not IP-only. TTL=24h; same key+body replays; same key+different body → 409 IDEMPOTENCY_CONFLICT; concurrent same key → 409 IDEMPOTENCY_IN_PROGRESS + Retry-After. Concurrent reuse of the same key is safe; on IDEMPOTENCY_IN_PROGRESS wait Retry-After and retry with the same key.
Sealed anonymous_client_id (agents). Omit on first request — server mints and echoes the same header (+ Set-Cookie duan_anon) on the response that entered idempotency scope, including 409 and 503. Resend on subsequent anon calls. Not a credential.
Optional correlation id. The server echoes it back (X-Request-Id response header and request_id) only if it matches [A-Za-z0-9._-]{1,128}; any other value is ignored and a fresh id is returned.
Request body
Response
Batch processed (may be partial success). Results keyed by client_ref inside each item — do not use array index for joins.
Example response
{
"results": [
{
"result": {
"short_url": "https://短.在线/a7x",
"short_url_ascii": "https://xn--s7y.xn--3ds443g/a7x"
}
}
]
}Changes
No recorded changes to this operation across all 1 revision of this API.