BC Correios error list

Error format Lerian BC Correios operations return errors as RFC 9457 problem details with the application/problem+json media type:

{
  "code": "BCC-0005",
  "correlationId": "req-7a3f9c2e",
  "detail": "Mail not found or access denied",
  "status": 404,
  "title": "Not Found",
  "type": "https://errors.lerian.studio/v1/BCC-0005"
}

Field definitions

type – A URI that identifies the error in the Lerian error catalog, built as https://errors.lerian.studio/v1/<code>.
title – The HTTP status text (for example, Not Found).
status – The HTTP status code.
detail – A human-readable explanation of this occurrence. For 5xx responses, the detail reads internal error. Branch on code instead. The detail of BCC-2009, BCC-2010, and BCC-2011 is in Portuguese.
code – A stable identifier for the error. Branch on this field. The tables below list the BCC-NNNN codes and the named code BANDWIDTH_LIMIT_EXCEEDED. Two errors can share a status and still differ here. BCC-0006 and BCC-2010 both answer 409. The code tells you which one you got.
errors – Optional list of individual error details, each with a location, a message, and a value.
correlationId – The request-scoped correlation identifier.

Request errors

These errors apply to the request itself. They cover its fields, its headers, the resource it names, and the state of the service that received it.

`code`	Description	Status
BCC-0001	Invalid Input. A value in the request is not valid. A `POST`, `PUT`, or `PATCH` request with a `Content-Type` other than `application/json` answers `415`. An `X-Idempotency` key already used for a different request answers `422`.	400, 415, 422
BCC-0002	Validation Failed. The request fails validation. A request-schema refusal answers `422`, and `errors` names the fields at fault. A field check answers `400`. A client-side refusal without a dedicated code also carries `BCC-0002`, with its own status.	4xx
BCC-0003	Invalid Cursor. The pagination cursor is not valid or has expired.	400
BCC-0005	Not Found. The resource does not exist for the caller’s tenant. On a send, the mail that `inReplyToMailId` names does not exist.	404
BCC-0006	Settings Already Exist. The tenant already has settings. Update them instead of creating them again.	409
BCC-0007	Rate Limit Exceeded. Too many requests arrived in the current window. Retry after the interval in the `Retry-After` header.	429
BCC-0008	Internal Server Error. An unexpected failure. The `detail` reads `internal error`.	500
BCC-0009	Service Unavailable. The service or a dependency it needs cannot complete the request. Try again later.	503
BCC-0010	Checksum Mismatch. The stored attachment failed its integrity check on download. The `detail` reads `internal error`.	500
BCC-0012	Duplicate Idempotency Key. A request with the same `X-Idempotency` key is still in process, and the response carries a `Retry-After` header. On a re-analysis, a key already used for a different mail answers `422`.	409, 422
BCC-0013	Concurrent Modification. Another request changed the resource first. Read the current values and apply your change again.	409
BCC-0014	Invalid State. The current state of the mail does not allow the action. A restore of a mail in the `CANCELLED` or `SENT` folder answers this code.	409
BANDWIDTH_LIMIT_EXCEEDED	The tenant used its attachment download budget for the current 60-second window. Retry after the interval in the `Retry-After` header.	429

Authentication errors

These errors apply to the token and to the permissions of the caller.

`code`	Description	Status
BCC-1002	Unauthorized. The request has no bearer token, or the service does not accept the token.	401
BCC-1003	Forbidden. The caller does not have permission for this operation. In multi-tenant mode, a token without a tenant claim also answers this code.	403

BC Correio and send errors

These errors apply to messages that you send to BACEN through BC Correio.

`code`	Description	Status
BCC-2001	BCB Authentication Failed. The tenant has no settings or no stored BC Correio credentials, or the service cannot read them. Check the tenant settings.	401
BCC-2002	BCB Service Unavailable. BC Correio refused the message, or the service did not send it. Send the message again with a new `X-Idempotency` key.	503
BCC-2009	Transmission In Progress. Another send with the same `X-Idempotency` key is in progress. Wait a few seconds, then retry with the same key.	409
BCC-2010	Transmission State Unknown. The service cannot tell whether BC Correio received the message. Do not send it again. Confirm non-delivery with BACEN through its manual channel before you use a new key.	409
BCC-2011	Transmission Failed. An earlier send with the same key failed, and BC Correio does not hold the message. Send the message again with a new key.	409
BCC-4003	Attachment Too Large For Transmission. The send request body is larger than 8 MB.	413

AI insight errors

These errors apply to a re-analysis of a mail by the AI provider that the tenant configured.

`code`	Description	Status
BCC-3002	AI Analysis Failed. The AI provider returned an error on a re-analysis. The `detail` reads `internal error`.	502
BCC-3004	AI Not Configured. AI is not configured for the tenant.	422
BCC-3005	AI No Content. The mail has no text to analyze. Its body is empty, and no text came from its attachments.	422
BCC-3006	Attachment Extraction In Progress. The service is still extracting text from the attachments of the mail. Try again in a few seconds.	409

Mails

Settings

Audit

Dashboard

Error handling

BC Correios error list

Request errors

Authentication errors

BC Correio and send errors

AI insight errors

​Request errors

​Authentication errors

​BC Correio and send errors

​AI insight errors

Request errors

Authentication errors

BC Correio and send errors

AI insight errors