# Error Contract Changes

This page covers v1-to-v2 migration notes for errors, status codes, retry behavior, and support
logging.

For the v2-native error model, start with [Error Handling](/docs/guides/api-conventions/error-handling)
and the [Error Reference](/docs/errors/index). Endpoint-specific status codes remain in the
[API reference](/api).

## What Changes From v1

v2 uses standard HTTP status codes and RFC 9457 Problem Details for error responses.

:::danger{title="Breaking: v1 error parsing no longer works"}

Update v1 clients so they do not depend on old plain-text errors, endpoint-specific error bodies, or
exception messages.

:::

In v2:

- `type` identifies the error category.
- `status` carries the HTTP status code.
- `detail` explains this request failure.
- `traceId` should be logged for support and troubleshooting.
- validation errors can include an `errors` array with field-level details.

See [Error Handling](/docs/guides/api-conventions/error-handling#error-response-format) for the full response shape.

## Status-Code Changes To Expect

:::caution{title="Do not assume v1-style 200 OK"}

Do not migrate clients by assuming v1-style `200 OK` success or error handling.

:::

Common v2 patterns:

| Status | Migration impact |
|--------|------------------|
| `400` | Invalid request parameters, body shape, type conversion, validation, or unsupported API version. |
| `401` | Missing, invalid, or revoked authentication. |
| `403` | Authenticated caller is not allowed to access the resource or operation where the endpoint exposes that outcome. |
| `404` | The addressed resource or subresource was not found or is not visible. |
| `406` | The request asks for a response media type the API does not provide. |
| `409` | The request conflicts with current resource state or a business constraint. |
| `415` | The request body uses an unsupported `Content-Type`. |
| `201` | Create operations can return `201 Created` instead of v1-style `200 OK`. |
| `202` | Some deletes can be deferred and return `202 Accepted`. |
| `204` | Deletes commonly return `204 No Content`; clients must not expect a response body. |

Endpoint-specific success and error responses are documented in `/api`.

## Validation Errors

Validation errors can include field-level issues in `errors[]`. Update client validation handling so
it can map:

- `scope`
- `path`
- `code`
- `message`

Treat `code` as endpoint-specific metadata rather than a fixed global enum unless an endpoint
documents a stable set.

## Retry Rules

Do not retry every non-2xx response. Use status and error type:

- retry only transient failures: `429 Too Many Requests` and `5xx` responses, honoring any `Retry-After` header.
- do not retry validation errors until the request is changed.
- do not retry authentication errors until credentials or tokens are corrected.
- do not retry business conflicts unless the client has refreshed state or changed the operation.

Always log `traceId` when available.