API Errors

Every error response from the IaaS APIs has the same body. The HTTP status and the code tell you what happened; the code prefix tells you in which area.

Error body format

Field	Type	Description
title	string	Short name of the error, in English.
description	string	Description in English. In validation errors, it names the field that failed.
translation	string	Description in Portuguese.
code	string	Three letters indicating the area, followed by six digits. Use this field in your error handling.

Example: a manager integration without the write permission calling a POST.

{
  "title": "Manager does not have permission to access this endpoint",
  "description": "Manager does not have permission to access this endpoint",
  "translation": "Gestor nao tem permissão para acessar esse endpoint",
  "code": "MIT000017"
}

Handle the error by the HTTP status and the code. The title, description and translation texts may change.

code prefix

Prefix	Where the error happened
MIT	Manager host (manager-api): authentication, permission and routing.
CIT	Consultant host (consultant-api): authentication, permission and routing.
AIT	Assignor host (assignor-api): authentication, permission and routing.
QIT	Generic error, on any host or service: nonexistent route, method not accepted, invalid body, internal error.
SET	Asset settlement (/settlement).
TRC	Receivables assignment (/trade_receivables).
TRF	Assignment files (/trade_receivables_files).
TRR	Asset sale and repurchase (/trade_resolve).
TTR	Public Securities Recorder (/trade_treasury).
ASR	Assignor onboarding (/assignor_registry).
ASS	Assignors (/assignor).
ACT	Assignment contract (/assignment_contract).
AAM	Receivables amendment (/asset_amendment).
ADF	Asset documents (/asset_document_files).
BSC	Bankslips (/bankslip_collection).
CSH	Accounts and statement (/cash_account).
TSF	Internal transfer (/transfer).
TRV	Transaction reversal (/transaction_reversal).
CMP	Portfolio composition (/composition).
WLT	Portfolio (/wallet).
EXP	Expenses (/expense).
IVR	Investor registration (/investor_registry).
IAD	Adhesion term (/investor_adhesion).
QTA	Quotas (/quota).
QOF	Offering control (/quota_offering_control).
TFQ	Fund quotas as assets (/trade_fund_quota).

A 400 with code QIT000001 means an invalid request body: the field with the problem comes in description.

Authentication

Header, API key and signature errors (*000007 to *000016 and *000020), and how to fix each one, are in Authentication Test.

Permission and route

After authenticating the request, the host checks whether your integration can call that route. A missing permission comes back as 401, not 403: do not look for a signature error when the code is one of these.

Status	code	When it happens	What to do
401	MIT000017	The manager integration does not have the permission the route requires: Read, Write or both.	Check the permission in the "Available on" block of the endpoint page and the status under Permissions, on the integration screen. See integration permission grant.
401	CIT000018	The consultant has no active link with the fund (fund_class_key) or does not have, in that fund, the permission the route requires.	Check the fund_class_key and the permission shown in "Available on". Consultant permissions are granted per fund. If the permission shows as Granted by the integration team, it cannot be configured in the portal: request it at integracao.dtvm@qitech.com.br.
401	AIT000017	The assignor integration does not have the read or write permission the route requires.	Contact integracao.dtvm@qitech.com.br.
400	*000009	The integration is deactivated.	Reactivate the integration (how) or contact the integration team.
404	QIT000404	The host does not expose that path.	On a documented route, it is almost always another profile's base URL: check the "Available on" block of the page and the base URL for your profile. Also check the path, without the base_url.
405	QIT000405	The path exists on the host, but not with that method.	Check the method on the endpoint page.

Retry and duplicates

In case of error, resend the request. If the resource already exists, the creation returns a duplicate error instead of creating another one: look up the existing resource.

Creation	Duplicate code	Status	How to look up the existing resource
Payment batch (settlement)	SET000009	409	Batch retrieval, by the batch external_id.
Settlement within a batch	SET000013	400	Settlement retrieval, by the settlement external_id.
Sale or repurchase batch	TRR000015	409	GET /trade_resolve/fund_class/{fund_class_key}/assignment/{assignment_external_id}, exposed only on the assignor host. Manager and consultant do not have this lookup.
Public Securities Recorder ticket	TTR000044	409	GET /trade_treasury/fund_class/{fund_class_key}/operations, looking for your external_id in the list.

Public Securities Recorder: always send external_id

In the Public Securities Recorder, external_id is optional. Always send it: without it, the API does not recognize a ticket that was already created.

Internal error

A 500 with QIT000500 is an error on QI's side. If it persists, send the request (without the private key), the time in UTC and the code to integracao.dtvm@qitech.com.br.