DEV Community: Kristi Hampson

Troubleshooting TSS API Rejections Without Panicking

Kristi Hampson — Tue, 01 Sep 2026 07:20:41 +0000

Categorise errors first

Not every rejection is the same. Some are data validation issues, some are authorisation, some are structural. Group them before you chase them.

Route by category, not by ticket

Data errors go to the operator who owns the source document. Authorisation errors go to compliance. Structural errors go to the engineering team.

Learn from repeat offenders

If the same error code keeps appearing, the fix is upstream, not in the API client. The TSS API troubleshooting guide captures the common patterns.

Keep the response payload

The JSON error response is the shortest path to the fix. Log it, link it to the declaration and make it searchable.

See how iCustoms turns TSS rejections into structured tasks — Watch a demo.

Troubleshooting TSS Declarations: What Goes Wrong and Why

Kristi Hampson — Mon, 31 Aug 2026 07:26:05 +0000

Four failure modes cover most incidents

Four failure modes cover most TSS declaration incidents. Each has a signature — and each has a fix that lives upstream of the mistake.

1. Supplementary declaration submitted with default commodity codes

Signature: duty corrections, HMRC queries. Root cause: auto-generated fields treated as final. Fix: block submission until commodity code fields carry a review flag.

2. Missed 10th-calendar-day deadline

Signature: late-submission notices, escalations. Root cause: month-end movements get the shortest window and ownership is unclear. Fix: work the calendar backwards from the 10th and assign named owners per lane.

For the exact deadline logic, see this TSS declaration cheat sheet.

3. UKIMS-authorised traders running full supplementary declarations

Signature: heavier monthly workload than peers. Root cause: no quarterly IMMI eligibility review. Fix: automate a UKIMS × Category 1 check per SKU.

4. Wrong route at inventory-linked ports

Signature: Full Frontier requirements discovered post-booking. Root cause: freight teams booking without route-check. Fix: gate booking on the port classification.

Fix upstream, not downstream

Solve the upstream causes and the incident tickets stop showing up.

Want to see the upstream fixes wired in? Watch a demo of iCustoms.

Troubleshooting Stuck TSS Movements

Kristi Hampson — Fri, 28 Aug 2026 07:07:06 +0000

When a TSS movement stalls, the root cause almost always sits in one of five places.

1. The commodity code is wrong or too shallow

Six digits where eight are required, or a code that doesn't match the description. Fix the master data, resubmit.

2. The at-risk position isn't defensible

No UKIMS, no evidence, or evidence that doesn't map to this shipment. Reclaim as at risk or delay until the paperwork holds.

3. Safety and security data has no owner

Ambiguity between trader and carrier is the classic failure. Assign ownership explicitly and audit it.

4. Movement reference vs vehicle mismatch

Trailer swap, different registration, missing container. Rebuild the reference against the actual vehicle before check-in, as covered in this TSS troubleshooting reference.

5. Reference built before customs entry

Impossible by design. If your system offers it, your system is lying to you.

If you'd like to see how iCustoms surfaces and resolves these failure modes automatically, watch a demo.

Troubleshooting TSS, ICS2, GVMS and NCTS Failures

Kristi Hampson — Thu, 27 Aug 2026 08:34:00 +0000

Most production incidents in this stack fall into a few families. Knowing the pattern shortens the fix.

GVMS check-in rejection

Almost always a data mismatch. Check vehicle registration, trailer detail, and that every declaration reference bundled into the Goods Movement Reference is present and correct. If one reference is missing, the GMR fails.

CDS declaration hangs

Often a commodity code issue: same code, different formatting, or a value that fails a duty calculation. Read the CDS response codes carefully rather than resubmitting.

ICS2 filing gap

A common failure mode is neither party filing because both assumed the other would. Confirm ICS2 responsibility per lane in writing and audit it. A Northern Ireland customs systems explainer covers the responsibility split.

NCTS unexpected requirement

Comes up when a route through Ireland was not flagged at planning. Once the driver is at the border it is late. Push route checks to the booking stage.

TSS validation errors

TSS validation errors are almost always the friendliest failures in the stack. They stop the entry before it reaches CDS, ICS2, GVMS or NCTS, which is why the input layer is where quality effort belongs.

Practical takeaway

Read the actual error, do not resubmit blindly. Every error names the system that surfaced it.

Want to stop chasing errors after the fact? Watch a demo to see how iCustoms.ai surfaces them at the entry point.

Troubleshooting Common TSS and CDS Submission Errors

Kristi Hampson — Tue, 25 Aug 2026 06:57:55 +0000

Most declaration errors show up in the same handful of fields. Here is how to spot them fast.

EORI mismatches

An XI EORI is often needed for Northern Ireland movements, alongside or instead of a GB EORI. If TSS or CDS rejects your declaration on the party identifier, check which EORI is registered against the trader profile.

Commodity code issues

Codes must be current and correctly structured. An outdated code will pass a quick eyeball test but fail validation in TSS or CDS.

The Northern Ireland trader guidance is useful when you are triaging whether the issue is with the movement type or the reference data.

Procedure code errors

Wrong procedure code combinations are one of the most frequent CDS rejections. If your TSS submission fails, procedure codes are the second thing to check after EORI.

Valuation and currency

Missing incoterms, currency mismatches or invoice value mismatches are common causes of holds. Fix them at data source, not at the portal.

CDS access delays

CDS access usually arrives within two hours, but can take up to five working days if HMRC needs extra checks. If you have just registered, that is expected, not broken.

Amendment loops

If you keep amending the same field, the problem is upstream data, not the portal. Fix the source, not the last mile.

Stop errors before they hit CDS. Watch a demo with iCustoms.

Common TSS Errors and What Causes Them

Kristi Hampson — Mon, 24 Aug 2026 07:21:50 +0000

"I can't find my TSS number"

This question comes up constantly, mostly because "TSS number" means three different things depending on context:

Your EORI number, issued by HMRC, identifies your business to customs.
Your UKIMS authorisation number, if you hold one, arrives in your UKIMS approval letter.
The TSS reference attached to a specific declaration or movement record, found in the portal next to that record. If you can't locate a reference, start with the record itself in the portal before contacting support.

Read the Full context on Northern Ireland customs guide for better understanding.

Declaration queries from vague goods descriptions

Goods descriptions need to be specific enough for customs to identify what's in the consignment. "Clothes" triggers a query. "Men's cotton knitted shirts, size XL" doesn't. This is one of the most common, and most avoidable, causes of delay.

Missing Goods Movement Reference at the port

For roll-on roll-off traffic, GVMS bundles declaration references into a single Goods Movement Reference before the vehicle can travel. Inside TSS, the GMR is built from declaration data already supplied, which is exactly why incomplete declarations at step 6 of the movement workflow cause problems at the port.

UKIMS eligibility rejections

UKIMS requires a clean customs and tax compliance record over three years, documented internal controls tracking goods from arrival to end use, and five years of accessible supporting evidence. Missing any of these at application stage is the most common rejection cause.

Watch a demo

Troubleshooting TRACES API Integration Errors

Kristi Hampson — Fri, 21 Aug 2026 07:26:44 +0000

Getting a Pass When You Expect a Fail

This usually means activity context wasn't sent with the code. A code approved for one activity can look valid if you only check the code itself. Always send country and activity together.

Confusing Invalid, Delisted and Mismatched

These are three different problems and need three different responses. A properly built TRACES API integration for ERPs returns distinct error semantics for each, so check that your integration surfaces the specific reason, not a generic failure flag.

Authentication Failures Mid-Run

Token-based authentication with rotation means a long-running bulk job can outlive its token. Build in a refresh step for bulk requests rather than assuming one token covers the whole batch.

Bulk Requests Timing Out

Large catalogue validations should be chunked rather than sent as one enormous request. Check documentation for recommended batch sizes before running your first full catalogue sweep.

Results Not Appearing in the Audit Trail

If a validation ran but didn't log, check that the request completed rather than erroring silently.

Watch a demo and walk through error responses with the team that built the API.

TRACES Code Validation Errors and How to Read Flags

Kristi Hampson — Thu, 20 Aug 2026 07:47:26 +0000

Most TRACES code validation errors come from four causes: a typo in the approval number, the wrong exporting country, the wrong activity section, or an establishment that has been delisted or suspended. The flag tells you which. Read it before you re-run anything, because three of those four are data problems on your side and only one is a change at the source.

Definition

An error flag is a machine readable reason a code did not validate, attached to the row that failed.

Reading the four flag types

Format or typo: the number does not exist as written.
Country mismatch: the code is not on that country's list.
Activity mismatch: the site is approved, but not for this activity.
Delisted or suspended: the approval is no longer current. ### Why the last one is different

The first three are fixable in your own records. A delisting is a real world change, and it is the one that causes border holds with demurrage and storage costs.

Debugging in order

Work from cheapest to most expensive.

Re-check the code against the supplier document.
Confirm the exporting country on the consignment.
Confirm the activity matches the goods.
Only then treat it as a source change. Manual checking hides this order, because a person searching the portal usually stops at the first plausible match and records a pass. Structured flags remove that guesswork, and understanding the pattern behind TRACES code validation errors makes triage much faster.

Keeping the evidence

Log the flag, the fix and the time. Up to 99% accuracy only helps if you can show what happened to the 1%.

FAQ

Why does the same code pass for one shipment and fail for another?
Approval is country specific and activity specific, so context changes the answer.

What if nothing looks wrong on my side?
Assume a delisting or suspension and confirm before shipping.

Do failed checks need recording?
Yes. Failures matter more than passes in an audit trail.

Find out how many hours your team could save on chasing failed codes. Watch a demo

Troubleshooting a Failed EU Establishment Check

Kristi Hampson — Wed, 19 Aug 2026 07:46:51 +0000

A shipment flagged at the border for establishment approval usually traces back to one of a handful of root causes.

Check the commodity code first

Before assuming the supplier isn't approved, confirm the commodity code is correct. A composite product misclassified as purely plant-based will fail an establishment check that was never triggered on the wrong code in the first place.

Confirm you're checking the right regulation

Food establishments approved under Regulation (EC) 853/2004 are listed separately from animal by-product establishments under Regulation (EU) 1069/2009. Checking the food list for a pet food ingredient supplier will return a false negative. Our EU animal-origin export requirements guide separates the two lists clearly.

Check the activity, not just the establishment

A facility can appear on the TRACES lists approved for one activity and not another. An establishment cleared for edible meat isn't automatically cleared for animal by-products, even at the same address.

Check how recent the data is

Approvals change without notice. A supplier that passed a check three months ago may have since been delisted. If a shipment fails unexpectedly, re-pull the current TRACES record rather than relying on a saved status.

When the code and the establishment both check out

If classification and establishment both confirm compliant, the remaining cause is usually a documentary mismatch, the paperwork doesn't reflect the establishment number correctly.

Preventing the repeat

Build re-validation into the booking step for every shipment, not a periodic review.

Watch a demo to see automated flags for delisted or mismatched establishments.

Debugging a Refused CHED: Working Backwards From the Documentary Check

Kristi Hampson — Tue, 18 Aug 2026 08:38:13 +0000

Start with what failed, not what shipped

When a Common Health Entry Document is refused, the instinct is to look at the goods. Look at the documentary check first, because that is where most refusals happen and it runs on every consignment before any physical inspection.

Run through the checks in order

Is the CHED type right? Four types exist: CHED-A for live animals, CHED-P for products of animal origin, CHED-PP for plants and plant products, CHED-D for high-risk food and feed of non-animal origin under increased controls. A composite food containing animal products belongs on a CHED-P. Cross-referencing the CHED documentary failure causes against your own refusal notes usually narrows this quickly.

Are all establishment codes valid and still listed? Check every approval number in Part 1, not just the producer. A delisted code behaves exactly like a wrong one.

Do the certificates agree with the CHED? Compare weights, species and descriptions field by field across the CHED and the health certificates. Any disagreement is a query waiting to happen.

Was the notice period met? Submission happens before arrival, and many border control posts enforce a minimum notice period.

Is the CHED reference in the customs declaration? A consignment can clear the health controls and still not be released.

Know when the trail ends

Amendment is possible while the document is on your side. Once Part 2 records the decision, it is final, and a refusal leads to re-export, destruction, or supervised transformation. So watch a demo if you would rather run this checklist automatically before submission than manually after refusal.

Troubleshooting TRACES NT: A Checklist for When Something Is Stuck

Kristi Hampson — Mon, 17 Aug 2026 08:45:39 +0000

Most TRACES NT tickets fall into four buckets. Working through them in order saves a lot of guessing.

1. Access problems

TRACES NT uses EU Login with two-factor authentication. Old TRACES Classic credentials do not exist, because the Commission decommissioned that platform in 2022. If someone cannot sign in, check whether they have an EU Login at all before checking anything else. Access itself is free.

2. Wrong document type

Four CHED types cover different goods: CHED-A for live animals, CHED-P for animal products, CHED-PP for plants and plant products, CHED-D for non-animal food and feed. A form that will not accept your product line is usually the wrong type rather than a bug.

3. Code and detail mismatches

Establishment codes must match official lists exactly. Certificate numbers and consignment details are entered by hand, so compare against the source document character by character before assuming a platform fault. Most border holds trace back here. The background on why this remains manual is set out in this explainer on why TRACES Classic was retired.

4. Obsolete references

If an internal system, template or supplier form still refers to the CVED, it is describing a document that has not been in use since the Classic shutdown. Fix the template, not the submission.

Escalation note

Before raising anything externally, capture the CHED type, the exact field, the source document value and the entered value. That short record resolves most cases without escalation.

See how iCustoms flags mismatched codes before they become holds: watch a demo.

Debugging TRACES NT Access: Four Failure Modes and Their Fixes

Kristi Hampson — Wed, 12 Aug 2026 07:55:14 +0000

Diagnose the layer before the symptom

Almost every TRACES NT access issue resolves to one of four causes: an unactioned approval, an EU Login credential problem, a duplicate organisation record, or a missing administrator. Identifying which layer failed saves days of guessing.

Failure one: status stuck on pending

Pending means the approver has not actioned the request yet. For an existing organisation that is your internal administrator. For a new organisation it is the competent authority. Contact the approver directly. Resubmitting creates noise without changing the outcome, which is set out clearly in this TRACES NT login troubleshooting guide.

Failure two: cannot log in

This is usually EU Login rather than TRACES NT. Reset the password through the EU Login portal, then confirm two-factor authentication points at a phone number you still control. Staff who changed devices without updating 2FA are a frequent cause.

Failure three: duplicate organisations

These appear when a colleague creates a new entry instead of joining the existing one. The result is split records and confused approvals. Correction requires competent authority intervention to merge or amend, so raise it as soon as you notice.

Failure four: no administrator left

If your only administrator leaves the business, internal approvals stop. Request administrator rights through the competent authority, then keep a minimum of two administrators permanently.

Escalation path

The TRACES helpdesk is reachable through the Help menu inside the platform. Competent authorities handle organisation level approvals.

Find out how iCustoms catches submission errors before a border control post does. Watch a demo.