Skip to main content

Response and error patterns

Use the OpenAPI contract for exact schemas. This page covers the patterns you should expect at a design level.

Resource-oriented responses​

Resource routes typically return structured JSON representing:

  • A session.
  • A source.
  • A checkpoint result.
  • A manifest or metadata view.
  • A cache or annotation object.

Action-oriented responses​

Action routes often return one of these outcomes:

  • Confirmation that the action succeeded.
  • A structured result describing the new state.
  • A job or operation handle.
  • A summary object that should be shown to a user before the next step.

Asynchronous workflows​

Some source workflows are naturally asynchronous.

Model those flows as:

  1. Start the work.
  2. Capture the returned identifier or job reference.
  3. Poll or retrieve the job status using the documented job route.

Error handling guidance​

When handling errors:

  • Treat authentication and authorization failures separately.
  • Treat missing resources as normal workflow outcomes, not exceptional programming bugs.
  • Treat optimistic-concurrency failures as retry or conflict conditions.
  • Treat validation failures as client mistakes that should be fixed before retrying.

Schema-level detail​

For exact field names, enums, required properties, and status codes, use the generated public OpenAPI contract rather than trying to infer details from route names alone.