Error handling

The Qwoty API uses standard HTTP status codes. 2xx means success, 4xx means the request must be fixed before retrying, and 5xx means something went wrong on our side.

Error body

Every error response is a JSON object with an error string. Validation errors add a details array that lists each problem:

{
  "error": "Validation error",
  "details": ["Field 'api_name' is required"]
}

Key	Type	Description
`error`	string	Short description of the error. Always present.
`details`	string[]	Present on validation errors only: one message per invalid field.
`success`	boolean	Some endpoints also return `"success": false`. Don’t rely on it: use the HTTP status.

There is no message key. Messages are meant for developers and may change: branch on the HTTP status, not on the exact text.

Status codes

400 Bad Request

The request is malformed or a field is invalid. Fix the request before retrying.

Invalid JSON

{
  "error": "Invalid JSON body"
}

Unknown or read-only field

{
  "error": "Validation error",
  "details": ["Field 'description' is read-only or unknown"]
}

Empty update

{
  "error": "No fields to update"
}

Unknown keys are rejected, not ignored: sending a field that the endpoint does not accept (for example a creation-only field such as api_name in a PATCH) returns 400.

401 Unauthorized

The token is missing or not valid.

Missing token

{
  "error": "Missing authorization token"
}

Invalid token

{
  "error": "Invalid or expired token"
}

Invalid or expired token is returned for an unknown token, a deleted (revoked) token, or a token whose role was deleted. Tokens do not expire on their own. See Authentication.

403 Forbidden

The token is valid but its role lacks the right required by the endpoint.

{
  "error": "Insufficient permissions. Requires customer:write"
}

See Permissions.

404 Not Found

The object does not exist, was deleted, or belongs to another workspace.

{
  "error": "Customer not found"
}

Some endpoints also return 404 when a referenced ID does not exist, for example an unknown catalog_ids entry when creating a product:

{
  "error": "Validation error",
  "details": ["Catalog(s) not found: 660e8400-e29b-41d4-a716-446655440001"]
}

409 Conflict

The request conflicts with existing data.

Duplicate api_name

{
  "error": "Validation error",
  "details": ["A product with api_name 'premium_widget' already exists"]
}

Category in use

{
  "error": "CATEGORY_REFERENCED_IN_DISCOUNT"
}

429 Too Many Requests

You sent too many requests in a short time. Wait and retry with exponential backoff. See Rate limits and retries.

500 Internal Server Error

An unexpected error occurred.

{
  "error": "Internal server error"
}

Some endpoints return a more specific message, for example Failed to create payment term. You can retry 500 errors with backoff; if the error persists, contact support.

Retry guidance

Status	Retry?
`400`, `401`, `403`, `404`, `409`	No. Fix the request, token or role first.
`429`	Yes, after a delay with exponential backoff.
`500` and other `5xx`	Yes, a few times with exponential backoff.

Getting help

If an error persists, contact support@qwoty.io with the endpoint, the HTTP status, the response body and the time of the request. Never include your API token.

Getting started

Core concepts

Resources

Compliance

Policies

Error handling

Error body

Status codes

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

409 Conflict

429 Too Many Requests

500 Internal Server Error

Retry guidance

Getting help

​Error body

​Status codes

​400 Bad Request

​401 Unauthorized

​403 Forbidden

​404 Not Found

​409 Conflict

​429 Too Many Requests

​500 Internal Server Error

​Retry guidance

​Getting help

Error body

Status codes

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

409 Conflict

429 Too Many Requests

500 Internal Server Error

Retry guidance

Getting help