Errors

The Pickware ERP API reports problems through the GraphQL errors array in the JSON body, not through HTTP status codes. Inspect the errors field on every response — it is the canonical signal that something went wrong.

HTTP status codes

The endpoint follows the GraphQL-over-HTTP convention: HTTP status codes describe the transport, not the GraphQL operation. Treat them as a coarse-grained signal and read the response body for the actual outcome.

HTTP status	When it appears	What to do
200 OK	The server received and executed (or attempted to execute) the GraphQL document. The response body still has to be inspected — it may contain errors for individual fields or for the whole operation.	Parse the JSON body. If errors is present, handle it according to its code.
400 Bad Request	The request body could not be parsed as JSON, or it is not a valid GraphQL request envelope.	Fix the client. The body usually does not contain a useful GraphQL errors array in this case.
401 Unauthorized	The Authorization header is missing or the bearer token cannot be validated at all.	Provide a valid token. See Authentication.
429 Too Many Requests	The merchant exceeded its rate-limit bucket and the API rejected the request before executing the GraphQL document.	Back off and retry after the retryAfter value in the body. See Rate limits.
5xx	A transient server-side problem.	Retry with exponential backoff. Include the requestId (when available) if you have to contact support.

In every other case — including operation-level problems such as missing scopes, validation errors, or "not found" — the HTTP status is 200 and the meaningful detail is in the errors array described below.

GraphQL error shape

GraphQL responses can contain both data and errors. A response with partial data may still include errors for fields that could not be resolved.

{
  "data": {
    "product": null
  },
  "errors": [
    {
      "message": "Product not found.",
      "path": ["product"],
      "extensions": {
        "code": "NOT_FOUND",
        "requestId": "req_01HX7KQY8Y2Y2G0K6S4KJ5W0F2"
      }
    }
  ]
}

Common error codes

Code	Meaning	Suggested action
UNAUTHENTICATED	The access token is missing, invalid, or expired.	Exchange your credentials for a fresh access token and retry the request.
FORBIDDEN	The token does not have the required scope.	Request the missing scope for the token.
VALIDATION_FAILED	The GraphQL document or variables are invalid.	Check the generated API reference for field names and input types.
NOT_FOUND	The requested resource does not exist or is not visible to the token.	Verify the identifier and token permissions.
THROTTLED	The token exceeded its current rate limit.	Wait for the retryAfter value in extensions.

Debugging requests

Every error includes a requestId in extensions when possible. Include this ID when contacting support so the Pickware team can find the failing request quickly.

For schema-level validation errors, compare your operation with the generated reference for fields such as products, stocks, and ProductFilterInput.