Skip to main content

Error codes

Every error code the services can return, generated from the services' own error catalogues.

INTEGR codes

CodeHTTP statusMessage
AUTH-INTEGR-001401Signature header missing on integrator-signed endpoint
AUTH-INTEGR-003401Signing key id not found for this integrator
AUTH-INTEGR-004401Signing key is retired
AUTH-INTEGR-005401Signing key is revoked
AUTH-INTEGR-006401Signature algorithm is not permitted for this endpoint
AUTH-INTEGR-007401Signature verification failed
AUTH-INTEGR-008401Signature timestamp is outside the permitted clock skew window
AUTH-INTEGR-009401Signature nonce has been replayed
AUTH-INTEGR-011401JWT does not carry a client_id claim
AUTH-INTEGR-012401Request body hash does not match signed value
CFG-INTEGR-014503Configured outbound signing key could not be loaded
INT-INTEGR-010503Integrator key resolution is temporarily unavailable
VAL-INTEGR-002400Signature header is malformed
VAL-INTEGR-013413Request body too large or unreadable

ETD codes

CodeHTTP statusMessage
AUTHZ-ETD-008403It is not this country's turn to act on the transit declaration.
AUTHZ-ETD-014403The caller could not be attributed to a State Party or REC. The credential is not bound to exactly one such tenant.
AUTHZ-ETD-015403This kind of caller may not perform customs acts. A stamp is made at a border by the administration that controls it.
AUTHZ-ETD-016403The caller is not entitled to act for this country.
AUTHZ-ETD-017403No submission arrangement has been configured for this caller. The AfCFTA Secretariat must record who may submit, and on whose behalf, before any declaration can be lodged.
AUTHZ-ETD-021403The formalities at the customs office of departure cannot be amended. A stamp is evidence of what an officer did; correct it by cutting a new stamp, not by editing the old one.
AUTHZ-ETD-036403This caller may see the declaration but may not add documents to it. Attaching is open to the countries the declaration concerns; ask the Secretariat if a delegation is missing.
AUTHZ-ETD-038403You may not administer users in that tenant. A State Party's administrator manages people inside their own customs administration; only the Secretariat may act on another's.
AUTHZ-ETD-069403This country's declarations are submitted by its Regional Economic Community. Its own system is not accepted while that arrangement is in force.
AUTHZ-ETD-103403The live AfCFTA system does not currently admit this organisation for sandbox traffic. The decision and its reason come from the live system; nothing about this sandbox is at fault, and retrying will return the same answer.
AUTHZ-ETD-105403The authenticated caller is not authorized to perform this request.
AUTHZ-ETD-111403You may read this declaration but not one of the sections you asked to include. The delivery ledger (include=deliveries) is open only to the Secretariat and to whoever may act for the country that filed the declaration; read again without it.
BUS-ETD-002409A transit declaration already exists for this country code and serial number.
BUS-ETD-006400The transit time range is invalid.
BUS-ETD-009409The requested operation is not valid in the declaration's current state.
BUS-ETD-010409The transit declaration serial number could not be generated.
BUS-ETD-019412The version you amended is no longer the current one — the declaration was changed in the meantime. Read it again and resubmit against the new version.
BUS-ETD-020409The submitted declaration is identical to the current version, so there is nothing to record. Check that your change reached the request body.
BUS-ETD-022409The transit declaration was being changed by another act at the same time. Nothing was recorded; send the request again.
BUS-ETD-025409This idempotency key was already used for a different request. Use a new key, or resend the identical request.
BUS-ETD-048409The organisation cannot move to the requested onboarding state from its current state.
BUS-ETD-052409Production credentials require certification first.
BUS-ETD-063409The goods cannot be released yet: the previous country has not stamped its transit.
BUS-ETD-070409Another Regional Economic Community already submits for this country. One country has one submitter, so withdraw the existing arrangement before recording this one.
BUS-ETD-072409This organisation has no arrangement on file. Record its participation or delegation before admitting it.
BUS-ETD-074409A Regional Economic Community with that code is already in the register.
BUS-ETD-077409Production access must be approved by the Secretariat before production credentials are issued.
BUS-ETD-080409The technical contact cannot be attached to this organisation. Use a different active account or resolve the existing organisation membership.
BUS-ETD-082409This transit is discharged at its declared office of destination, not at this office. If the goods must be cleared elsewhere, the departure country amends the office of destination first.
BUS-ETD-083409Goods can only be recorded as entering or leaving the customs territory at a border office. This office is registered as inland; correct it in the customs office register if that is wrong.
BUS-ETD-085409ITS closes a transit itself only when it can no longer follow the goods. This one it can still follow, so it ends the ordinary way: the destination stamps its entry, then discharges at the declared office of destination.
BUS-ETD-091409That person is already recorded as a contact for a different organisation. Name someone else, or use an address that is not yet attached to another State Party or REC.
BUS-ETD-096409This environment mirrors the arrangements recorded on the production system and cannot change them. Record the change there and it appears here automatically.
BUS-ETD-099409No such contact is recorded for this organisation, so there is no invitation to send. Name the contact first, then send the invitation.
BUS-ETD-101409A partner credential already exists for this organisation and environment, so the blocked operation cannot be closed as never issued. Rotate the existing credential instead.
BUS-ETD-102409That partner credential operation is not in a state operator reconciliation can settle. Wait for work that is still applying to finish, and name a single operation when more than one is blocked.
BUS-ETD-108409This ledger stream is not halted, so there is nothing to resume.
BUS-ETD-126409This arrangement is already on file from that effective date. To restore one that was withdrawn, reactivate its existing row; to record a new period, give it a different effective_from.
BUS-ETD-132409A request with this idempotency key is being processed right now. Send the request again to receive the declaration it issues.
BUS-ETD-133409This country has already recorded its entry for this declaration and has not exited since. If you are resending a request, send it with the Idempotency-Key it first carried.
BUS-ETD-134409This declaration has no cargo manifest yet: the manifest is produced when the declaration is discharged.
INT-ETD-033503No endpoint is configured for this country, so the announcement could not be delivered. Register one before the backlog can drain.
INT-ETD-045503The sign-in for a system ITS calls is not fully configured, so it could not be called. The log names the missing configuration key.
INT-ETD-046502A partner system answered in a shape this contract does not define. The call was treated as unavailable rather than guessed at.
INT-ETD-053503The credential provider is unavailable. Try again later or contact the operator.
INT-ETD-056502The credential provider rejected the request. Check the provider configuration or request and try again.
INT-ETD-138503Your e-mail choices could not be reached just now. Nothing was lost: try again in a moment, and the same request is safe to repeat.
ONB-ETD-060503Credential request still in progress; resend the same request.
RES-ETD-001404The requested transit declaration was not found.
RES-ETD-012404No such governance dataset. The datasets are rec-membership, rec-submission-delegation, state-party-participation, service-account-binding, intake-limit, transit-rule and operations-setting.
RES-ETD-024404No such version of this transit declaration.
RES-ETD-029404No such reference dataset. This service serves countries, currencies, transport-modes, package-kinds, terms-of-payment, customs-offices and hs-codes, and serves them read-only.
RES-ETD-030404No such delivery for this recipient.
RES-ETD-035404No such attachment on this declaration.
RES-ETD-041404No posting exists with that identifier.
RES-ETD-043404No declaration matches those details. Check the serial number and the TIN, or scan the QR code on the document.
RES-ETD-047404The organisation onboarding record was not found.
RES-ETD-050404The organisation is not an ITS tenant.
RES-ETD-066404No such receiving endpoint.
RES-ETD-097404No such notification.
RES-ETD-100404No such partner credential operation exists for this organisation and environment.
SYS-ETD-023503The transit declaration could not be signed, so nothing was recorded. A signing key is configured but did not work; this is an outage on our side. Send the request again once it has been fixed.
SYS-ETD-026500This transit declaration has no stored version contents. Nothing can be served for it until it is re-issued.
SYS-ETD-057500The declaration is sound but could not be rendered as a printable document. Nothing about the declaration has changed; try again, and report it if it persists.
SYS-ETD-106500This version's anchoring proof could not be assembled from what was recorded. This is a fault on our side; the version itself is unaffected.
SYS-ETD-109502The consortium ledger could not be read just now. Nothing is lost; try again shortly.
VAL-ETD-003400A submitted value is not in the reference vocabulary.
VAL-ETD-004400The station does not exist or does not belong to the stated country.
VAL-ETD-005400The value is not one of the allowed values for this field.
VAL-ETD-007400The declared transit route is not valid: the departure and destination countries must differ, and a border stamp declaring the next country must name a country other than the one recording the stamp.
VAL-ETD-013400No file was uploaded. Attach the filled-in template returned by the template endpoint.
VAL-ETD-018428This amendment must carry an If-Match header naming the version being amended. Its value is the content hash of the version you read.
VAL-ETD-027400A value in this declaration carries more precision than can be represented exactly. Round it to at most 15 significant digits and resubmit.
VAL-ETD-028400An amendment must say why it was made. Put the reason in envelope.amendment_reason.
VAL-ETD-034400A listing parameter could not be read. Each filter must be field<operator>value over a filterable field, dates must be ISO-8601 instants, state must be one of REGISTERED, DEPARTED, TRANSITED, ARRIVED, DISCHARGED or CANCELLED, and order-by must name a sortable column with a direction of asc or desc.
VAL-ETD-037400At least one file is required. Send every document for this act in one request: they become one version and one announcement.
VAL-ETD-039409That officer is already posted to that station. To change when the posting runs, withdraw it and create a new one; the withdrawn posting stays in their history.
VAL-ETD-040409That posting has already been withdrawn. Reload the officer's postings to see the current ones.
VAL-ETD-042400The posting's effective window is not valid. effective_to must not be earlier than effective_from.
VAL-ETD-044400A TIN is required. Send the declarant's or the consignee's TIN in the X-Party-Tin header, beside the serial number.
VAL-ETD-051400The credential environment must be sandbox or production.
VAL-ETD-058400That is not a leaflet or a language this document has. Use leaflet=I, leaflet=II or leaflet=BOTH, and a BCP-47 language tag.
VAL-ETD-059400The requested include is not available. Valid includes are corridor, versions, deliveries, guarantee_status, tracking, integrity and manifest.
VAL-ETD-064400That is not an act this declaration accepts. Use depart, transit, entry or discharge.
VAL-ETD-065400The receiving endpoint is not usable as declared. base_url must start with https://, OIDC_CLIENT_CREDENTIALS requires both a client id and a token URL, contract_version must be v1, and a union must name the member it registers for.
VAL-ETD-067400That is not a State Party in the AfCFTA register. Choose a country from the list.
VAL-ETD-068400That is not a Regional Economic Community in the AfCFTA register. Create the REC first, then record its members.
VAL-ETD-071400A Regional Economic Community cannot submit for a country it does not contain. Record the country as a member first.
VAL-ETD-073400Say which member this delegation covers, or set coverage to ALL_MEMBERS to cover the whole union. A row that names a member cannot also cover all of them.
VAL-ETD-075400A Regional Economic Community code is up to 16 characters, using capital letters, digits and hyphens.
VAL-ETD-079400That is not a field this organisation listing can be ordered by.
VAL-ETD-084400Say whether this is a BORDER office, where goods enter or leave the customs territory, or an INLAND one.
VAL-ETD-086400That filter cannot be applied to organisations.
VAL-ETD-092400This office cannot face that country: the two share no frontier.
VAL-ETD-093400Only a BORDER office can face another country. Set the type to BORDER, or clear the neighbouring country.
VAL-ETD-094400The office on the other side is not in the register yet. Record the neighbouring country and leave the counterpart until that administration adds it.
VAL-ETD-095400The counterpart office is not in the neighbouring country recorded for this office.
VAL-ETD-098400That is not an African Union member state.
VAL-ETD-104400A sandbox admission request must name the organisation by its registered external type and external id, and must ask about the sandbox environment.
VAL-ETD-105400An office's code cannot be changed. Register the office under its new code and withdraw this one.
VAL-ETD-110400A ledger listing parameter is not valid: a stream id is 64 lowercase hexadecimal characters, limit is 1 to 20, and before is 1 or more.
VAL-ETD-128400sequence_nos must list between 1 and 500 notification sequence numbers.
VAL-ETD-129400Give both the latitude and the longitude of the office, or leave both empty.
VAL-ETD-130400This request must carry an Idempotency-Key header. Choose a value that is unique to this request, and send the same value again if you resend it.
VAL-ETD-131400The Idempotency-Key header must be at most 64 characters.
VAL-ETD-134400as_of must be an ISO-8601 instant with a UTC offset, such as 2026-08-11T09:30:00Z, and cannot be sent together with version: send one or the other.
VAL-ETD-135400muted_categories must list at most 50 categories, each 1 to 40 characters; send an empty list to unmute everything.
VAL-ETD-136400A customs office named on this request is recorded as closed in the customs-office register. Use an open office, or have your administration reopen it in its register if it was closed by mistake.
VAL-ETD-137400muted_categories may name only categories whose e-mails can be stopped, listed in stoppable_categories; send an empty list to receive every e-mail.
VAL-ETD-138400format must be json, asycuda-awmds, or the code of an active manifest format the Secretariat publishes.
VAL-ETD-139400The manifest format was not saved: its code must be new and is never changed, and its template must produce a sample manifest, well-formed when its media type is XML or JSON.

UM codes

CodeHTTP statusMessage
AUTHZ-UM-009403You may not grant that role
AUTHZ-UM-010403You may not administer users in that tenant
INT-UM-004503The identity provider is unavailable
INT-UM-005502The identity provider did not disable the account
INT-UM-015502The identity provider did not retain the realm role
INT-UM-018502The identity provider did not remove the second factor
INT-UM-020502The identity provider did not apply the change
INT-UM-021502The identity provider refused the username change because the realm does not allow username edits; set editUsernameAllowed
RES-UM-001404No such user
VAL-UM-002409A user with that email or username already exists
VAL-UM-003409More than one identity matches that email or username
VAL-UM-006409You cannot deactivate your own account
VAL-UM-007409This is the last active holder of a required role in this tenant
VAL-UM-008400No such role in this tenant
VAL-UM-011400That column cannot be sorted on
VAL-UM-012400The paging cursor could not be read
VAL-UM-013400This listing does not support filter expressions
VAL-UM-014400No such realm role in the identity provider
VAL-UM-016409This user has no identity in the identity provider
VAL-UM-017400The status filter must be ACTIVE or DEACTIVATED
VAL-UM-019409You cannot reset your own second factor
VAL-UM-022400An e-mail address is required
VAL-UM-023400A telephone number in international form is required, such as +254700000000

IDEM codes

CodeHTTP statusMessage
BUS-IDEM-002409A request with this Idempotency-Key is already in progress
VAL-IDEM-001400The Idempotency-Key header is required on this endpoint
VAL-IDEM-003422This Idempotency-Key was already used with a different request

AN codes

CodeHTTP statusMessage
CFG-AN-008500Ledger anchoring is misconfigured
CFG-AN-009500The ledger anchoring schema is not usable
DATA-AN-007500Stored anchoring data does not reproduce the batch root
INT-AN-006502The ledger is unavailable
VAL-AN-001400The stream is not configured for anchoring
VAL-AN-002400Subject key must be 1 to 255 characters
VAL-AN-003400Entry is not a well-formed anchor entry
VAL-AN-004400Entry field cannot be encoded
VAL-AN-005400Merkle tree argument is out of range

ATT codes

CodeHTTP statusMessage
CFG-ATT-005503Attachment scanning is required but no scanner is configured
RES-ATT-007404No such attachment
SYS-ATT-006500Attachment could not be stored
SYS-ATT-009503Attachment scanning is temporarily unavailable
VAL-ATT-001400ownerType, ownerKey, filename and content are required
VAL-ATT-002415File content type is not permitted, or does not match what was declared
VAL-ATT-003413File exceeds the maximum permitted size
VAL-ATT-004400File was rejected by malware scanning
VAL-ATT-008400File is empty

FGW codes

CodeHTTP statusMessage
CFG-FGW-001500The Fabric connection is misconfigured

Other codes

CodeHTTP statusMessage
CV-100400Content is not valid JSON
CV-101400contentType, contentKey, changeType and content are required
CV-102404Content version not found
CV-103409Concurrent append for this content key, please retry
CV-104409Expected current version does not match; re-read and retry
CV-105400Field value exceeds its maximum length
CV-106400Signatures must each carry a role, alg, kid and jws
CV-107400Metadata must be a flat object of string keys and values
DV-100400A verification code needs a document type and key
DV-101404Verification code not found
DV-102500Could not mint a unique verification code
S3-100503Failed to connect to storage service
S3-101401Invalid storage credentials
S3-102500Invalid storage endpoint configuration
S3-110404Object not found
S3-111409Object already exists
S3-112500Failed to upload object
S3-113500Failed to download object
S3-114500Failed to delete object
S3-115500Failed to copy object
S3-116500Failed to list objects
S3-117500Failed to retrieve object metadata
S3-118500Failed to generate presigned URL
S3-119400Invalid object key
S3-130404Bucket not found
S3-131409Bucket already exists
S3-132409Bucket is not empty
S3-133500Failed to create bucket
S3-134500Failed to delete bucket
S3-135500Failed to list buckets
S3-136400Invalid bucket name
S3-190500Storage operation failed
S3-191400Validation failed
S3-192403Access denied to storage resource
WF-100404Workflow document not found
WF-101409Workflow document already exists
WF-102404Workflow version not found
WF-103404No active workflow version for document
WF-104404Workflow status not found
WF-105404Workflow operation not found
WF-106404No step defined for this transition
WF-120404Workflow instance not found
WF-121409Instance already exists for this entity
WF-122409Instance is in a terminal status
WF-140409Transition not allowed from current status
WF-141403Insufficient permissions for this operation
WF-142409Guard rejected the operation
WF-143400Comment is required for this operation
WF-144409Concurrent modification, please retry
WF-145409Document is locked by another user
WF-146409Document is administratively locked
WF-147403Caller does not own the lock
WF-148404No active lock to release
WF-149400Lock type not enabled for this document
WF-150404Scheduled transition not found
WF-151409Scheduled transition is not pending and cannot be cancelled
WF-152409Scheduled transition is not in a failed state and cannot be retried
WF-160500Persisted entity is not bound to a workflow instance — call WorkflowEntityService or WorkflowRuntimeService#initializeInstance in the same transaction
WF-161500Workflow enforcement could not verify the binding for a persisted entity (registry, JTA transaction, or repository unavailable) and workflow.enforcement.mode=enforce fails closed rather than allowing an unverified insert through
WF-190500Workflow operation failed
WF-191500Guard bean not found in CDI
WF-192500Owner resolver bean not found in CDI
WF-193403Instance does not belong to the caller's tenant
WF-194403This document is tenant-scoped; use the instance-scoped operation instead of a document-wide read

Platform codes

CodeHTTP statusMessage
ERR-000500Internal Error
ERR-001400Unexpected Request
ERR-002404Record/Resource Not Found
ERR-003500Encoding Error
ERR-004500Decoding Error
ERR-005401Un-authorized access
ERR-006403Forbidden from access
ERR-007500Failed to parse file
ERR-008500Failed to build object
ERR-009501Operation NOT Supported
ERR-010404No Record(s) Found
ERR-011500Un-expected NULL value while processing
ERR-012409Duplicate Records Found
ERR-013400Failed to store this Record
ERR-014400Failed to store this Record. Some request Constraints failed. Missing or unexpected request values
ERR-015400Validation failed
ERR-016500Database query failed
ERR-017500Service operation failed
ERR-018502External service integration failed
ERR-019401Security violation
ERR-020429Too Many Requests
ERR-021404{0} with {1} {2} not found
ERR-022405This method is not allowed on this path
ERR-023415This Content-Type is not supported by this endpoint
ERR-024406This endpoint cannot produce any of the media types you accept
ERR-025503This service is temporarily unavailable
ERR-026409The request conflicts with the current state of the resource
ERR-099500An un-expected Error occurred

BC codes

CodeHTTP statusMessage
RES-BC-005404No delivery of that version exists for this recipient
VAL-BC-001400aggregateType, aggregateKey, versionNo, eventType and payloadKind are required
VAL-BC-002400Broadcast payload must be non-empty, valid JSON
VAL-BC-003400Field value exceeds its maximum length
VAL-BC-004400Every recipient must carry both an id and a type
VAL-BC-006400payloadSha256 must be 64 lowercase hexadecimal characters

BIO codes

CodeHTTP statusMessage
VAL-BIO-001400Upload exceeds the maximum permitted size
VAL-BIO-002400Upload exceeds the maximum permitted number of rows
VAL-BIO-003400Unsupported file type. Provide a .xlsx, .xls or .csv file

IL codes

CodeHTTP statusMessage
VAL-IL-001400A rejection read must name exactly one tenant, or explicitly read across tenants
VAL-IL-002400A rejection read's window must not start after it ends
VAL-IL-003400A rejection read's status range must lie within 100-600 and must not start after it ends
VAL-IL-004400A rejection read's path-parameter filter must name a parameter and a value
VAL-IL-005400The rejection listing cursor is not one this listing issued
VAL-IL-006400A capped rejection count's cap must be at least 1 and at most 1000000

NF codes

CodeHTTP statusMessage
VAL-NF-001400noticeKey, category, severity, titleKey, titleFallback and dedupeKey are required
VAL-NF-002400A notice must name at least one audience
VAL-NF-003400A TENANT or COUNTRY audience must carry a value
VAL-NF-004400Notice params must be a JSON object
VAL-NF-005400Field value exceeds its maximum length
VAL-NF-006400At most 500 notices can be marked read in one call
VAL-NF-007400Muted categories must be 1 to 40 characters each, and at most 50 of them