Errors

The API reports failures through the HTTP status. The response body follows one of these formats, so clients in strongly typed languages must be ready to deserialize all of them.

Formats

Request errors (4xx with a code)

Validations and business rules return a top-level code and the list of details:

{
  "code": "resourceValidationErr",
  "errors": [
    {
      "code": null,
      "reason": "invalid value",
      "message": "must be a valid id",
      "property": "@.id"
    }
  ]
}

Field	Type	Description
code	string	Top-level code (see the catalog below)
errors	array	Details of each problem found
errors[].code	string or null	Detail-specific code
errors[].reason	string	Reason for the error (e.g. invalid value, optional)
errors[].message	string	Human-readable message
errors[].property	string	Path of the property that caused the error (e.g. @.documentNumber; @ refers to the identifier in the URL)

Authentication errors (401 and 403)

{ "message": "Invalid API Key" }

See the possible messages in Authentication.

Resource not found (404)

When the identifier is valid but the resource does not exist, the API returns 404 with an empty body.

Internal error (500)

{
  "errorEventId": "a1b2c3d4e5f6",
  "message": "Internal server error."
}

Send the errorEventId to support to speed up the investigation.

Rate limit (429)

More than 1 request per second returns 429. See Rate limit.

Code catalog

resourceValidationErr

• Status: 422
• When it happens: the request body has a required field missing, a wrong type or a value outside the rules.
• Common causes: required field not sent (reason: optional); invalid CPF/CNPJ or one already registered for another customer (reason: document number already exists); text above the maximum length.
• How to fix: check the field given in errors[].property against the endpoint's field table.
• Customer endpoints: create and update customer, email, phone, location; add label; create custom field answer.
• Employee endpoints: create employee (includes email already used, reason: duplicated) and update employee (includes invalid identifier in the URL, property: @.id).
• Material endpoints: create and update material (on update, includes invalid identifier in the URL, property: @.id).
• Product endpoints: create and update product (includes code already used and, on update, nonexistent product with message: product/service not found).
• Product type endpoints: create and update product type (on update, includes nonexistent type with message: products type not found).
• Products and services endpoints: create and update product or service (on update, includes nonexistent record with message: product/service not found).
• Work order type endpoints: create and update work order type (on update, includes invalid identifier in the URL, property: @.id).
• Service endpoints: create and update service (on update, includes nonexistent service with message: work service not found).
• Equipment endpoints: create and update equipment (includes duplicate number or qrCode, type, customer or custom field not found and, on update, invalid identifier in the URL with property: @.id).
• Equipment type endpoints: create and update equipment type (on update, includes invalid identifier in the URL, property: @.id).
• Part endpoints: create and update part (required fields, duplicate name or code, nonexistent part type, negative minimum quantity), archive a part that is already archived, unarchive an active part, and add or remove an equipment type.
• Part type endpoints: create and update part type (name missing or duplicate), archive a type that is already archived and unarchive an active type.
• Part unit endpoints: create and update unit (required fields, nonexistent part or storage, status field sent) and actions with an incompatible status (reason: invalid status) or a triage storage on release.
• Storage endpoints: create and update storage (includes name already used and, on update, nonexistent storage with message: storage not found).
• Movement endpoints: make a movement and a transfer by external identifier (nonexistent product, storage or order, insufficient balance, invalid quantity).
• Vehicle endpoints: create and update vehicle (includes brand or model not found by name and, on update, nonexistent vehicle with message: vehicle not found).
• Work order endpoints: create and update order (includes customer, work order type, location, request, contract or agreement not found, duplicate number and, on update, invalid identifier in the URL); create and update task; attach file; comment; link equipment or label; add product or service; remove product (v2); change form answers.
• Task endpoints: add and remove secondary employee.
• Service request endpoints: create and update request.
• Quotation endpoints: create, update, decline and cancel quotation (includes nonexistent quotation and a status that does not allow the action); add label.
• Answered form endpoints: change answers.
• File upload endpoints: upload file.

parametersValidationErr

• Status: 422
• When it happens: a query parameter is invalid.
• Common causes: limit outside 1–100; offset outside 0–200000; sort value not accepted; invalid date in a filter (created_at>=:2026-02-31).
• How to fix: see Pagination and Filters and sorting.
• Customer endpoints: all lists.
• Employee endpoints: list employees.
• Material endpoints: list materials.
• Product endpoints: list products.
• Product type endpoints: list product types.
• Products and services endpoints: list products and services.
• Work order type endpoints: list work order types.
• Service endpoints: list services.
• Equipment endpoints: list equipment.
• Equipment type endpoints: list equipment types.
• Part endpoints: list parts.
• Part type endpoints: list part types.
• Part unit endpoints: list part units.
• Storage endpoints: list storages.
• Movement endpoints: list movements and transfers.
• Vehicle endpoints: list vehicles, brands, models and uses.
• Work order endpoints: list orders and order tasks.
• Task endpoints: list tasks and secondary employees.
• Service request endpoints: list requests.
• Quotation endpoints: list quotations.
• Label, rating, service agreement and deadline contract endpoints: lists.

uriValidationErr

• Status: 422
• When it happens: the identifier in the URL is not valid or belongs to another account.
• Common causes: mistyped or truncated identifier; identifier from another environment or another account.
• How to fix: use the id exactly as returned by the API. A valid identifier that does not exist returns 404, not this error.
• Customer endpoints: all that receive an identifier in the URL.
• Employee endpoints: retrieve employee.
• Material endpoints: retrieve material.
• Product endpoints: retrieve and update product.
• Product type endpoints: retrieve and update product type.
• Products and services endpoints: retrieve and update product or service.
• Work order type endpoints: retrieve work order type and list its custom fields.
• Service endpoints: retrieve and update service.
• Equipment endpoints: retrieve equipment.
• Equipment type endpoints: retrieve equipment type.
• Part endpoints: retrieve, archive, unarchive and add or remove equipment type.
• Part type endpoints: retrieve, archive and unarchive part type.
• Part unit endpoints: retrieve unit and all actions.
• Storage endpoints: retrieve and update storage.
• Movement endpoints: retrieve movement.
• Vehicle endpoints: retrieve and update vehicle, and retrieve vehicle use.
• Work order endpoints: all that receive the order or item identifier in the URL.
• Task endpoints: retrieve task and manage secondary employees.
• Service request endpoints: retrieve request.
• Quotation endpoints: retrieve and update quotation; manage labels.
• Answered form endpoints: retrieve and change form.
• Label, rating, service agreement and deadline contract endpoints: retrieve agreement or contract.

resourceAlreadyExists

• Status: 409
• When it happens: the resource you are trying to create or link already exists.
• Common causes: adding to the customer a label that is already linked.
• How to fix: query the resource before creating it, or treat the 409 as success when the goal is to ensure the link.
• Customer endpoints: add label to customer.
• Equipment type endpoints: create and update equipment type with a name already used in the account.
• Work order endpoints: link equipment, add label and add service already present in the order.
• Quotation endpoints: add label already present in the quotation.

resourceNotAllowed

• Status: 422
• When it happens: the operation is not allowed for the resource in its current state.
• How to fix: read errors[].message to find out which rule prevented the operation.
• Customer endpoints: none.
• Storage endpoints: all, when the account does not have the inventory control module (reason: storage control disabled).
• Movement endpoints: all, when the account does not have the inventory control module.

resourceNotFoundErr

• Status: 422
• When it happens: a resource referenced in the request body was not found (different from 404, which means the resource in the URL does not exist).
• How to fix: check the identifier given in errors[].property.
• Customer endpoints: none.

resourceNotFound

• Status: 422
• When it happens: the resource in the URL does not exist, in part, part type and part unit endpoints (these endpoints have no 404).
• Common causes: identifier of a deleted resource or one from another environment.
• How to fix: check the identifier; list the resources to get a valid id. Note that the code does not end in Err, unlike resourceNotFoundErr.

resourceLockedErr

• Status: 422
• When it happens: the resource is locked for changes (e.g. a finished work order).
• Customer endpoints: none.
• Part endpoints: update, archive, unarchive and add or remove equipment type of a nonexistent part.
• Part type endpoints: update, archive and unarchive a nonexistent part type.
• Part unit endpoints: install, uninstall, discard, return and release a nonexistent unit.
• Work order endpoints: change form answers of a locked order.
• Answered form endpoints: change form answers of a locked order.

cannotArchivePrimaryLocation

• Status: 422
• When it happens: attempt to archive (archived: true) a customer's primary location.
• How to fix: set another location as primary before archiving this one.
• Customer endpoints: update customer location.

cannotChangeCustomerOfPrimaryLocation

• Status: 422
• When it happens: attempt to move the primary location to another customer.
• How to fix: set another location as primary in the current customer before moving this one.
• Customer endpoints: update customer location.

cannotSetArchivedLocationAsPrimary

• Status: 422
• When it happens: attempt to set an archived location as primary.
• How to fix: unarchive the location first (archived: false).
• Customer endpoints: update primary location.