Errors

Errors are a fundamental component of Wix's APIs, providing critical information and guidance when something goes wrong. Most of Wix's errors follow a standardized format, as described below.

Error properties

PropertyDescription
Status codeSee the HTTP status code table below.
messageTextual description that provides a brief explanation of the error.
detailsAdditional contextual information about the error, including either applicationError or validationError. See the tables below.

HTTP status codes

Every API call will return a status code. If something went wrong, you'll receive an error code that defines the type of error that occurred.

Status code types include:

  • 2xx - Everything is OK.
  • 4xx - There was a problem with the request. Usually you can fix the request and try again immediately.
  • 5xx - There was a problem in Wix's service, there's nothing wrong with the request. Try again later.
HTTP Status CodeDescription
200 - OKSuccess. No error.
400 - Bad RequestOne or more request parameters is wrong or missing, or you didn't pass validation.
401 - UnauthorizedThe system wasn't able to authenticate you (missing or incorrect Authorization header, expired token, etc.). Occasionally returned when you don’t have permissions to call this API.
403 - Permission deniedThe system authenticated you, but you don’t have permissions to call this API.
404 - Not foundResource not found / doesn't exist.
409 - ConflictThe resource you are attempting to create already exists or has a different revision than the one you're attempting to update, or another conflict with the server state.
428 - Precondition requiredPreconditions must be met for the request to be successful (for example, a required field wasn't passed, or the passed gift card is out of funds).
429 - Resource exhaustedResource usage was exhausted (for example, a previously used one-time-token, or too many requests).
500 - Internal server errorAn error occurred on Wix's server. Try again later.
501 - Not implementedThe endpoint hasn't been implemented yet.
503 - Service unavailableThe service that you’re trying to access is temporarily unavailable. Try again later.
504 - Gateway timeoutThe underlying service didn't respond in a timely manner. Try again later. If you're trying to query for data, you may try a smaller page size or a simpler filter.

Application error data

An application error occurs when the service business-logic decides to reject the request. This includes codes like UNAUTHENTICATED, PERMISSION_DENIED, NOT_FOUND, ALREADY_EXISTS, ABORTED and RESOURCE_EXHAUSTED.

PropertyDescription
codeIdentifier that categorizes and signifies the specific error.
descriptionDetailed explanation of why the error occurred.
dataAdditional contextual information related to the error.

Examples

Copy
Copy

Validation error data

A validation error occurs when input data fails to meet predefined criteria or constraints set by the system. This type of error serves to enforce rules such as correct data formats, required fields, or value ranges. This includes rules like OUT_OF_RANGE and INVALID_ARGUMENT. Validation errors are 4xx types. Multiple violations may be returned in one response.

PropertyDescription
fieldViolationsArray of validation issues found in individual fields.
fieldViolations.fieldField name.
fieldViolations.descriptionDetailed explanation of why the error occurred for the specified field.
fieldViolations.violatedRuleSpecific rule or constraint that was violated by the input in the identified field.
fieldViolations.ruleNameName of specific rule or constraint that was violated. For example, "VALIDATION_ERROR".
fieldViolations.dataAdditional contextual information related to the field violation.

Example

Copy

System errors

A system error occurs when there's an exception in the system, server is down, or some dependent service or database is down.
These errors are sent empty by design. System errors are 5xx types.

Example

Copy
Did this help?