Handling of userErrors and userWarnings in Integration API

Created August 22nd at 10:19am

Why you must check for API execution errors#

When using Centra’s Integration API, you can determine whether an execution went successfully by:

Checking an HTTP status
Checking userErrors (for mutations only)
Checking userWarnings (for mutations only)

While checking the HTTP status might be considered a well-known practice, on its own it will not be enough to ensure you have achieved the desired result.

In short, you should always check the HTTP status for both queries and mutations, consider mutations with non-empty userErrors as failed, and at least somehow report userWarnings.

HTTP status#

200 “OK”: the request was executed successfully. For queries, this means successful execution. For mutations, the outcome is more complex; see the sections below.
400 “Bad Request”: the query or mutation was invalid (e.g., due to a GraphQL syntax error; wrongly formatted JSON; missing required parameters).
403 “Forbidden”: the provided token was invalid or expired.
429 “Rate Limited”: the request was rate-limited; see more details here.
499 “Client Closed Request”: the client closed the connection before the server could send a response. Usually, it only happens when the execution takes too much time.
500 “Internal Error”: an internal server error occurred. Please try again, and if it remains, contact Centra.

Only responses with the 200 status code are considered successful.

User errors#

The userErrors field is a part of every mutation payload. See for example the accountCreatePayload:

type AccountCreatePayload implements Payload {
    account: Account
    userErrors: [UserError!]!
    userWarnings: [UserWarning!]!
}

If a response contains a non-empty userErrors, it means:

It’s an error (or multiple errors) that most likely is connected to data or a request body,
Nothing was modified on the Centra’s side,
You should not repeat a failed request until an underlying issue is fixed.

For instance, updateAccount can return “Could not find an account with id 999” in an attempt to provide a non-existent account ID.

The UserError type contains two fields:

type UserError {
    message: String!
    path: [String!]
}

message is a string containing an explanation, as the one above,
path is a list of fields in the executed mutation where our system spotted an error. It’s especially useful to identify the issue amongst multiple inputs, such as one of dozens of prices provided in setPrices.

Our recommendation is to always check whether the userErrors field is not empty, assume it can contain multiple errors, and include path in the payload.

User warnings#

When it comes to user warnings, they behave similarly to user errors, but assume a different meaning: it’s something that did not prevent the execution.

A common case is when one of many independent inputs fails, while others could be handled. For example, setCategoryDisplays can produce a warning when duplicated displays are provided: Skipped duplicated input for display with ID 999; setPrices can skip wrongly used prices: Individual variant prices are not supported for bundles, skipped.

We recommend that you always check whether the userWarnings field isn't empty. If it isn't, you should report the warnings in a way that makes sense for your application, whether that's logging them, displaying them to the user, or both.