HTTP 202 vs 201: created now, or accepted for later?

Return 201 Created when the request has already created the resource by the time you respond. Return 202 Accepted when you have only accepted the work and it will finish later. A 201 describes and links to the new resource; a 202 describes the request's current status and points to where the client can check on it, because the result doesn't exist yet.

The definitions come from RFC 9110, the HTTP semantics standard. The worked example is Sume's API: its API reference and the Video Generation docs. All were read on 2026-09-28.

What is the difference between status codes 200, 201 and 202?

All three are success codes. They differ in what exists when the response arrives:

When should an API return 201 Created?

When the thing the client asked for exists once you answer: a record, an account, a settings object. RFC 9110 says the new resource is identified by a Location header or, without one, by the request's target URI, and that the 201 body typically describes and links to what was created.

Sume's POST /v1/formats is an example. It creates the Format in the key's workspace before it answers, and the 201 carries the contents_url and package_sha the next call needs. A slug the workspace already uses is a 409, never an overwrite. Create a Sume Format over the API walks through the call.

When should an API return 202 Accepted?

When the work continues after the response. RFC 9110 calls the 202 intentionally noncommittal: the request might or might not eventually be acted upon. Its purpose is to let a server accept work without the client's connection staying open until the work is done.

Sume's POST /v1/videos answers 202 Accepted with the job's id, a polling_url and status: "pending". Agent Completions do the same for the same reason: an agent turn opens a sandbox, calls tools and may generate media, which takes far longer than an HTTP request should stay open, so the create call returns 202 with a receipt. The asynchronous request-reply pattern describes the rest of that flow.

A job record exists at once, so why not 201 for a job?

Because the client didn't ask for a job; it asked for a video. The job id is real the moment the server answers, but the output is not. A 202 tells the client the outcome is still pending, so no one mistakes the status line for the result. Sume's docs put it this way: a 2xx means the job exists and paid work is in flight; it does not mean the job finished.

Can one API use 200, 201 and 202?

Yes, and a client should branch on the code. Sume answers 201 when it creates a Format or a workspace grant on one, 202 for video generation jobs, and both 200 and 202 on POST /v1/images, depending on whether the images finished inside the wait. The docs' rule for that endpoint is to check the status code, not the body shape. 202 Accepted vs 200 OK covers the 200 case in detail.