Errors

The error response format of the Configo API and the full list of error codes.

When a request fails, the API responds with an HTTP status code and a JSON body that identifies the error.

Error format

{
  "id": 4019,
  "code": "ORDER_STATUS_NOT_FOUND",
  "message": "The order status does not exist in this project."
}
Field Type Description
id integer Stable numeric error ID
code string Stable error code. Branch on code or id, never on message
message string Human-readable explanation in English. It may change

Some errors add fields with details. They are listed in the table below and on the endpoint pages.

Validation errors

REQ_VALIDATION_FAILED caused by a malformed body lists every problem in errors:

{
  "id": 2001,
  "code": "REQ_VALIDATION_FAILED",
  "message": "The request was improperly formatted or contained invalid data.",
  "errors": [
    {
      "code": "invalid_type",
      "expected": "string",
      "path": [
        "name"
      ],
      "message": "Invalid input: expected string, received undefined"
    },
    {
      "code": "too_big",
      "maximum": 100,
      "inclusive": true,
      "origin": "number",
      "path": [
        "products",
        0,
        "discount_percent"
      ],
      "message": "Too big: expected number to be <=100"
    }
  ]
}

path points to the field. errors is absent when the same code is returned for a rule checked outside the schema, for example an unknown role_uuid.

Errors without an error object

A few responses carry only {"message": "..."}:

Status Body When
401 {"message": "Unauthorized"} No Authorization header, or the token is invalid, expired or revoked
500 {"message": "Internal Server Error"} An unexpected error on Configo's side

The widget API and the OAuth token endpoints have their own formats.

Error codes

Authorization (1xxx)

id code Status Meaning
1001 AUTH_INSUFFICIENT_SCOPE 403 The token lacks a scope the endpoint requires
1002 AUTH_TRUSTED_CLIENT_REQUIRED 403 Only Configo's own applications may do this
1003 AUTH_NO_ACCESS 403 Not allowed; e.g. reading roles without the needed permissions, unlinking the last sign-in method
1004 AUTH_NO_PROJECT_ACCESS 403 The user's project role lacks the permission the endpoint requires
1009 AUTH_PERMISSIONS_EXCEED 403 A role cannot be given permissions the caller does not hold

Request (2xxx)

id code Status Meaning
2001 REQ_VALIDATION_FAILED 400 The request is malformed or contains invalid data; see errors
2002 REQ_NO_DATA_PROVIDED 400 A PATCH request contained no fields to update
2003 REQ_FILE_NOT_ATTACHABLE 400 A file control value refers to a file that is missing, from another project or expired
2004 REQ_FILE_NOT_ALLOWED 400 The file is too large or its format is not allowed for a file control

Resources (3xxx)

id code Status Meaning
3001 RES_NOT_FOUND 404, 400 The resource does not exist or is not visible to the user. In a request body (400): a referenced resource does not exist
3002 RES_ALREADY_EXISTS 409, 400 The resource already exists, e.g. a duplicate tag name or contact field, an existing member

The API answers 404 RES_NOT_FOUND rather than 403 when the user may not see a resource, so its existence is not revealed. This includes a project whose owner's subscription has lapsed.

Business rules (4xxx)

id code Status Meaning Extra fields
4001 BILL_SUBSCRIPTION_EXPIRED 403 The user, or the project owner, has no active subscription
4002 LIMIT_PROJECT_COUNT_REACHED 403 The plan's project limit is reached
4003 PROJECT_OWNER_REQUIRED 403 Only the project owner may do this; also: removing the owner, the owner leaving
4004 ORDER_STATUS_TRANSITION_NOT_ALLOWED 400 The funnel's transition rules forbid this status change
4005 ORDER_INSUFFICIENT_STOCK 409 A status-change automation could not write off stock shortages, warehouse_uuid
4006 ORDER_LOSS_REASON_REQUIRED 400 A canceled status needs a loss reason
4007 ORDER_REQUIRED_FIELD_MISSING 400 The contact is missing fields the target status requires fields
4008 TASK_ENTITY_NOT_FOUND 400 The task's linked order or contact does not exist
4009 LIMIT_MEMBER_COUNT_REACHED 403 The plan's member limit is reached
4010 AUTOMATION_INVALID 400 The automation does not fit the event catalog reason
4011 EMAIL_SMTP_PASSWORD_REQUIRED 400 An SMTP password is required
4012 ORDER_DELETED 409 The order is deleted; restore it first
4013 CONFIGURATOR_FORMULA_INVALID 400 A configurator formula or product name template does not parse reason
4014 BILL_MANAGED_BY_PARTNER 403 The subscription is managed by a partner
4015 BILL_INSUFFICIENT_BALANCE 402 Not enough balance
4016 BILL_TARIFF_IN_USE 409 The plan is in use and cannot be deleted
4017 BILL_PAYMENT_EXPIRED 409 The payment has expired
4018 BILL_SUBSCRIPTION_NOT_PENDING 409 The subscription is no longer awaiting payment
4019 ORDER_STATUS_NOT_FOUND 400 The status does not exist in this project
4020 ORDER_CONTACT_NOT_FOUND 400 The contact does not exist in this project
4021 ORDER_USER_NOT_MEMBER 400 The responsible user is not a member of this project
4022 ORDER_LOSS_REASON_NOT_FOUND 400 The loss reason does not exist in this project
4023 ORDER_STATUS_REQUIRED 400 An order's status can be changed but not removed
4024 ORDER_PRODUCT_NOT_PRICED 400 A configured product could not be calculated from its configurator details
4025 MEMBER_SELF_EDIT_FORBIDDEN 403 A member cannot change their own role
4026 BILL_TARIFF_PRICE_TOO_LOW 400 An own plan's price is below its base plan's price
4027 BILL_SUBSCRIPTION_STATE_CONFLICT 409 The action does not match the current subscription
4028 BILL_TRIAL_UNAVAILABLE 409 The trial was already used or a subscription exists
4029 CONTACT_EMAIL_REQUIRED 400 The contact has no email address to send to
4030 EMAIL_SENDER_NOT_CONFIGURED 400 The project has no email sender configured
4031 LIMIT_STORAGE_REACHED 403 The file storage of the project owner is full

Codes 4014–4018 and 4026–4028 come from billing operations available only to Configo's own applications.

Operations (5xxx)

id code Status Meaning Extra fields
5002 WAREHOUSE_INSUFFICIENT_STOCK 409 A stock movement would go below zero
5003 WIKI_PAGE_LOCKED 409 Another user is editing the wiki page holder
5004 WAREHOUSE_DEFAULT_REQUIRED 400 The default warehouse cannot be unset; make another one the default
5005 WAREHOUSE_RETURN_ALREADY_DONE 409 A return exceeds what is left to return for that product on the order
5006 FUNNEL_DEFAULT_REQUIRED 400 The default funnel cannot be unset; make another one the default
5007 FUNNEL_LAST_CANNOT_BE_DELETED 400 A project must keep at least one funnel
5008 FUNNEL_HAS_ORDERS 400 The funnel still has orders
5009 COMPANY_HAS_RECEIPTS 409 The company is the supplier of warehouse receipts and cannot be deleted
5010 WAREHOUSE_RECEIPT_CANCELED 409 The receipt has already been canceled
5011 WAREHOUSE_RECEIPT_USED 409 Stock from the receipt has already been moved, so it can't be canceled
5012 ROLE_IN_USE 409 Members still have the role; move them to another role before deleting it
5013 FILE_IN_USE 409 The file is still used by a material, configurator, document template, receipt or product