Hi there,
We’re making an update to the Prismic Migration API error format.
If your code doesn’t directly depend on the response body of errors, you don’t need to do anything.
For most projects, that’s the case, success responses remain unchanged, and only the shape of error responses is affected.
What Changed
Previously, error responses could vary and sometimes returned inconsistent payloads.
In some cases, responses were declared as application/json but returned plain text instead.
Going forward, errors will always return proper JSON following this type:
type ResponseError = {
message: string
details?: {
property?: string // (optional) the field that failed validation
value: unknown // the rejected value
error: string // a string explaining the failure
}[]
}
Why the Change
This update both fixes a bug (errors incorrectly returned plain text while declaring application/json), and improves consistency. With the new format, error responses are always valid JSON and more actionable, making it easier to debug migrations quickly and reliably.
When It Takes Effect
- The new format will go live on November 3.
Action Required
If you’re using the Prismic client for migrations and rely on error.response, you’ll need to:
- Upgrade to the latest Prismic client.
- Update your error handling logic to account for the new shape.
If you’re not handling errors directly, no action is needed.
If you have any questions about this, feel free to drop them below.