Troubleshooting¶
Common questions and solutions organized by feature area.
Digital Link Resolution¶
Why do I get JSON instead of an HTML redirect?
The GTIN1 resolver uses content negotiation to determine the response format. When no Accept header is present (or */*), the resolver defaults to an HTML redirect. However, some HTTP clients send headers that prefer JSON, which causes the resolver to return JSON or linkset data instead.
To explicitly request an HTML redirect, include Accept: text/html:
# Returns a redirect (no Accept header defaults to HTML)
curl -IL 'https://gtin1.com/01/00614524740689'
# Explicitly requests HTML redirect
curl -IL 'https://gtin1.com/01/00614524740689' \
-H 'Accept: text/html'
To request machine-readable data, use the appropriate Accept header:
# Request linkset data
curl 'https://gtin1.com/01/00614524740689' \
-H 'Accept: application/linkset+json'
# Request JSON-LD
curl 'https://gtin1.com/01/00614524740689' \
-H 'Accept: application/ld+json'
The resolver supports four content types, selected by the Accept header:
| Accept Header | Response |
|---|---|
text/html (or no header) |
HTML redirect to the product information page |
application/json |
Machine-readable product data |
application/linkset+json |
GS1 linkset per RFC 9264 |
application/ld+json |
JSON-LD with schema.org/GS1 vocabulary |
Tip
Browsers send Accept: text/html automatically. If your API client receives unexpected JSON instead of a redirect, check the Accept header your client sends by default.
My GTIN returns 400 Bad Request
A 400 Bad Request response means the GTIN in the URI failed validation. The resolver enforces the GS1 check digit algorithm, so the GTIN must be correctly formatted.
Common causes:
- Wrong number of digits. GTINs must be exactly 8, 12, 13, or 14 digits. A GTIN with 10 or 11 digits is not valid.
- Non-numeric characters. The GTIN path segment must contain only digits.
- Invalid check digit. The last digit of every GTIN is a check digit calculated from the preceding digits. If it does not match, the request is rejected.
Example error response (for JSON clients):
{
"error": "Invalid GTIN",
"status": 400,
"details": "GTIN must be 8, 12, 13, or 14 digits, got 11 digits"
}
How to verify your GTIN:
- Confirm it is 8, 12, 13, or 14 digits long.
- Use a GS1 check digit calculator to validate the last digit.
- If your barcode data is a UPC-A (12 digits) or EAN-13 (13 digits), the resolver accepts both. It pads to GTIN-14 internally.
Note
A 400 for a path with uneven AI/value segments (e.g., /01/09506000134352/10) or an unrecognized Application Identifier will also be returned. Ensure all path segments follow the /AI/value pair format.
Why do I get 406 Not Acceptable?
A 406 Not Acceptable response means the resolver cannot provide data in the content type you requested.
This happens when your Accept header exclusively requests a representation that is not available for the given resource. For example, requesting application/linkset+json for a product that does not have linkset data, with no fallback types accepted.
Solution: Broaden your Accept header to include fallback types:
# Narrow - may return 406 if linkset is unavailable
curl 'https://gtin1.com/01/00614524740689' \
-H 'Accept: application/linkset+json'
# Broader - falls back to JSON or HTML if linkset is unavailable
curl 'https://gtin1.com/01/00614524740689' \
-H 'Accept: application/linkset+json, application/json;q=0.9, text/html;q=0.8'
PNG QR codes return 400 Bad Request
PNG format for QR code generation has been deprecated. Requests using ?fmt=png now return a 400 Bad Request with the message:
PNG format is no longer supported. Use fmt=svg, fmt=eps, or fmt=pdf.
Use one of the supported formats instead:
https://gtin1.com/01/00614524740689?fmt=svg
https://gtin1.com/01/00614524740689?fmt=pdf
https://gtin1.com/01/00614524740689?fmt=eps
You can also use the shorthand ?qr parameter, which defaults to SVG output:
I only see 404 for AI 00, 253, 414, 8017, etc.
Currently, only GTIN (AI 01) is fully resolved with product data, linksets, and redirects. Other Application Identifiers are recognized in the URI structure but return a 404 Not Found with a message indicating the AI is not yet supported.
Examples of unsupported AIs:
| AI | Identifier | Status |
|---|---|---|
| 00 | SSCC (Serial Shipping Container Code) | Not supported |
| 253 | GDTI (Global Document Type Identifier) | Not supported |
| 255 | GCN (Global Coupon Number) | Not supported |
| 414 | GLN (Global Location Number) | Not supported |
| 417 | Party GLN | Not supported |
| 8017 | GSRN (Global Service Relation Number) | Not supported |
| 8018 | GSRN (recipient) | Not supported |
These AIs are part of the GS1 Digital Link standard and may be supported in future releases. For now, use AI 01 (GTIN) for product resolution.
Tip
Additional Application Identifiers within a GTIN URI are supported as qualifying data. For example, batch (AI 10), serial (AI 21), and expiration date (AI 17) are parsed and used when included alongside AI 01: https://gtin1.com/01/00614524740689/10/LOT123/17/261231
Organization & Permissions¶
I can't access my organization's data
Access to organization data is controlled by your membership role. If you receive a permission error, your current role may not have sufficient privileges.
GTIN1 membership roles and their access levels:
| Role | Access |
|---|---|
| Viewer | Read-only access to organization data |
| Contributor | Can create and edit products, brands, and trade items |
| Administrator | Full management access including member management |
| Owner | All permissions, including billing and organization settings |
To check your role: Go to your organization's settings page and look at the Members section.
To request a role change: Ask an Administrator or Owner of your organization to update your membership role.
I can't import or export data
Data import and export operations require the Contributor role or higher (Contributor, Administrator, or Owner). If you have the Viewer role, you can only read data.
Ask an Administrator or Owner to upgrade your role to Contributor if you need import/export access.
EPCIS API¶
I get a duplicate event error (409 Conflict)
EPCIS events are identified by a unique event hash derived from their content. If you submit an event that matches an existing event, the API returns 409 Conflict:
This is by design. EPCIS events are immutable records. Once captured, an event with the same content cannot be captured again. The response includes the ID of the existing event for reference.
Common causes:
- Retrying a request that already succeeded.
- Sending the same event payload from multiple systems.
If you need to correct an event, capture a new corrective event rather than re-submitting the original.
I get 'Could not determine organization' from the EPCIS API
This error means the API could not associate your request with an organization. The EPCIS API supports two authentication methods, and each requires organization context:
Method 1: API Key (recommended for integrations)
Include your API key in the X-API-Key header. The key is automatically linked to your organization:
curl -X POST https://gtin1.com/api/epcis/capture \
-H 'X-API-Key: your-api-key-here' \
-H 'Content-Type: application/json' \
-d '{"epcisBody": {"eventList": [...]}}'
Method 2: Session auth (browser-based)
If you are logged in and belong to multiple organizations, you must specify which organization to use with the ?org= query parameter:
If you belong to exactly one organization, it is selected automatically.
Warning
If your API key is expired, inactive, or invalid, authentication will fail silently and the organization context will not be set. Verify your API key is active in your organization's settings.
Authentication¶
Google login doesn't work
GTIN1 supports Google OAuth for sign-in. If Google login is not working:
- Check that cookies are enabled. OAuth requires session cookies to complete the authentication flow.
- Try a private/incognito window. Browser extensions can sometimes interfere with OAuth redirects.
- Clear your browser cache. Stale session data can cause authentication loops.
If the problem persists, use the email login option instead. GTIN1 sends a one-time login code to your email address as an alternative to social login.
Note
Google login requires the profile and email OAuth scopes. If your Google account has restricted third-party access, you may need to allow GTIN1 in your Google account security settings.
My magic login code expired or isn't working
Email login codes have a 15-minute expiry window and a maximum of 5 attempts before a new code is required.
If your code is not working:
- Check the time. Codes expire 15 minutes after they are sent. Request a new one if the window has passed.
- Check your attempt count. After 5 incorrect entries, the code is invalidated. Request a fresh code.
- Check your spam folder. Login codes are sent from the GTIN1 transactional email system.
- Request a new code. Go back to the login page and enter your email again to receive a fresh code.
Tip
If you are not receiving login emails at all, check that your email provider is not blocking messages from GTIN1. Adding the sender address to your contacts can help.
Notifications¶
I stopped receiving notifications
Notifications depend on several settings that can each prevent delivery. Check the following:
1. Channel enabled and verified
Each notification channel (email, SMS) must be both verified and enabled. Go to your notification settings to check:
- Is the channel enabled? (You may have disabled it previously.)
- Is the channel verified? (Unverified channels do not receive notifications.)
2. Product subscription preferences
Notifications are sent per product subscription. Each subscription has per-event-type toggles (recall alerts, safety alerts, expiration reminders, etc.). Verify that the event types you expect are turned on for the relevant product.
3. Unsubscribed via email link
If you clicked an unsubscribe link in a previous notification email, that specific product subscription may have been disabled. Re-enable it from your notification settings.
4. Organization membership
You must be a member of the organization that owns the product to receive organization-level notifications. If your membership was removed, notifications for that organization's products will stop.
Note
Recall and safety alert notifications are opt-out by default and are enabled for all new subscriptions. Other notification types (firmware updates, warranty expiry, expiration reminders) may need to be explicitly enabled.