Copy page

Migrating from v1

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 and the Error Reference. Endpoint-specific status codes remain in the API reference.

What Changes From v1

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

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 for the full response shape.

Status-Code Changes To Expect

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.