Skip to content

#161 · Public API: Clearer Error Types in Generated SDKs

Availability: General Availability

Error responses across the Escape Public API (v3) now carry explicit, semantic schema names. Every endpoint returns the same JSON payloads it always did, so direct HTTP integrations need no changes. If you regenerate an SDK from the updated OpenAPI spec, you'll see a handful of error-type renames that make decoded errors easier to read and reuse.

What's New

  • Named error schemas: the 400, 404, 409, and 500 responses now expose BadRequest, PaginationError, NotFound, Conflict, and InternalServerError as semantic schema names in the spec.
  • Consistent types across endpoints: regenerated SDKs use one semantic type per error shape, so you can share error-handling code across every endpoint that returns the same error.
  • Spec matches reality on GET /scans/{scanId}/targets: the declared 400 schema is now a single PaginationError, matching what the server actually returns.

Why It Matters

Until today, SDKs generated from our spec produced awkward error types like ListProfiles400Response or UpdateProfile400Response, one per operation, even when the payload was identical. Writing shared error-handling meant juggling a dozen near-duplicate types. With semantic names, one handler can cover every list endpoint's pagination error, another can cover every validation error, and so on. AppSec tooling that wraps the SDK ends up with cleaner imports, fewer surprises during audits, and fewer places to update when a new endpoint shows up.

How to Get Started

  • Call the API directly with JSON: nothing to do. Payloads are byte-for-byte identical.
  • Use an SDK and don't regenerate: nothing to do.
  • Use an SDK and regenerate from the new spec: update imports to the new type names. See the Compatibility section below for the exact renames.

Compatibility

Hard-breaking changes

None.

Soft-breaking changes

Wire payloads and HTTP status codes are unchanged. Regenerated SDKs and strongly-typed consumers will see type names and shapes change.

  • SDK error-type renames: identical inline error schemas used to produce one Go, TypeScript, or Python type per operation, with names derived from the alphabetically-first operation that referenced them. They now collapse into one semantic type per error shape. Typical renames you'll see after regeneration:

    Before (example) After
    ListProfiles400Response PaginationError
    UpdateProfile400Response BadRequest
    GetProfile404Response NotFound
    IgnoreScan409Response Conflict
    CreateAssetComment500Response InternalServerError

    Update imports and type references to the new names. Payload fields are unchanged.

  • GET /scans/{scanId}/targets 400 schema narrowed: the declared 400 used to be a union of BadRequest and PaginationError. The server has only ever returned the pagination variant on this endpoint, so the spec now declares a single PaginationError. Regenerated SDKs drop the union wrapper. Hand-written error handlers only need to match on "Invalid cursor" for this endpoint. Runtime responses don't change.

Non-breaking changes

  • Named schemas in the OpenAPI spec: every 400, 404, 409, and 500 response now carries an explicit title and description for BadRequest, PaginationError, NotFound, Conflict, and InternalServerError. Payload shapes for reference:

    HTTP Schema Shape
    400 BadRequest { "message": "Bad Request", "details": string }
    400 PaginationError { "message": "Invalid cursor", "details": string }
    404 NotFound { "message": "Not found" }
    409 Conflict { "message": "Conflict on the following field", "field": string, "instanceId": uuid }
    500 InternalServerError { "message": "Internal Server Error", "details": string }

  • No changes to operations, paths, methods, parameters, request bodies, success responses, or authentication.

What's Next

We keep improving the Public API, and there's more on the way.

Learn More

Questions?

Have a question? Reach out on your dedicated support channel (Slack, Microsoft Teams, or whichever channel we've set up with your team), or email us at support@escape.tech.