API Error Reference

This section provides a detailed overview of the error types returned by the Koncili Financial Integration API.

---

Important Notes:

• This table lists all known errors that may occur during integration with the Koncili API.
• Each entry includes an HTTP status code, an internal code formatted as {httpCode}-{internalCode} (e.g., 404-1), a standard message, and the associated endpoints.
• For errors not explicitly listed, please refer to the RFC 7807 standard.
• For technical inquiries, contact our support team: suporte@koncili.com.br

Reference Table

Code	HTTP Status	Endpoints	Description	Solution
400-0	400	All endpoints	Invalid values in the payload
400-2	400	All endpoints	Channel does not support API import
400-3	400	POST /order		Conflicting dates
403-1	403	All endpoints	The account is inactive
403-2	403	All endpoints	The account is not authorized to operate on this channel
404-1	404	All endpoints	The specified account does not exist
404-2	404	All endpoints	The specified channel does not exist
404-3	404	GET /order DELETE /order	The specified order does not exist
403	403	All endpoints	{"response": "NO_TOKEN"} Missing or expired token	Generate a new token via /public/api/auth/token
403	403	All endpoints	Unauthorized IP address	Whitelist the IP via /externalapi/ip-segmentation
502	502	All endpoints	Communication failure	Verify the request body and retry after a few seconds
404	404	All endpoints	Incorrect endpoint	Confirm the endpoint in the correct environment (sandbox or production)
500	500	All endpoints	Internal API error	Send the details (endpoint, timestamp, request body) to integracaoapi@koncili.com

Error Interpretation

Error Code: A combination of the HTTP status and a unique internal code (e.g., 404-3).

1. 4xx Errors: Client-side issues or malformed requests.
2. 5xx Errors: Server-side issues (typically temporary).

Response Format

By default, API error responses are formatted as follows:

{
  "errorMessage": "Channel invalid_channel not found",
  "errorCode": "404-2",
  "errorSource": "KIE"
}

For a malformed payload—in this example, an order sent with a status not accepted by the API:

{
  "errorMessage": "Bad Request",
  "errorDetails": [
    {
      "message": "JSON decoding error: Invalid ChannelStatusType value. Accepted values are: INVOICED, PAID_WAITING_DELIVERY, CONCLUDED, CANCELED"
    }
  ],
  "errorCode": "400-0",
  "errorSource": "KIE"
}

The errorSource field can assume two values:

1. KIE (Koncili Internal Error): Errors related to business logic.
   • Typical scenarios:
     • Payload validation
     • Data conflicts
     • Business rule violations
2. TPE (Third Party Error): Failures in external integrations.
   • Typical scenarios:
     • Marketplace APIs are unavailable
     • Partner service timeouts
     • Unexpected formats in external responses

Recommended Error Handling Flow

Note

TPE type errors are usually resolved automatically in subsequent attempts. If they persist for more than 15 minutes, please contact our technical team.