Troubleshooting and FAQ
Find what you see in the tables below, then follow the action. When you ask for help, share only the HTTP status and the error code. Never share your consumer secret or an access token.
Token endpoint
These come from https://apim.kairosinnovations.dev/oauth2/token.
| What you see | Likely cause | What to do |
|---|---|---|
HTTP 401 with invalid_client | The consumer key or secret is missing, wrong or has been replaced, or HTTP Basic authentication was not used. | Enter the credentials you were issued again and check that you use HTTP Basic authentication. Never log the secret. |
A response without access_token | An unexpected token response. | Stop. Contact your IFMS integration coordinator. Note only the HTTP status and the error code. |
| HTTP 5xx | A temporary failure of the token service. | Retry with controlled exponential backoff. Do not rotate your credentials automatically. |
| A TLS certificate error | A certificate, hostname or trust-store problem, or something intercepting the connection. | Stop and investigate. Never turn off certificate checks, and never use cURL's -k option. |
Telemetry gateway
These come from https://gw.kairosinnovations.dev/api/v1/ingest/telemetry.
| What you see | Likely cause | What to do |
|---|---|---|
HTTP 401 Unauthorized, gateway code 900902 | The access token is missing, expired or invalid. | Get a new token and retry once. If the retry also returns 401, see I get 401 even with a token. |
HTTP 403 Forbidden, gateway code 900901 | The token came from Sandbox Keys. The telemetry API has no sandbox endpoint. | Generate Production Keys and get a new token. See the Sandbox Keys warning. |
HTTP 403 Forbidden or a "blocked" message, without code 900901 | Your application is not allowed to call the API, for example because its subscription is blocked. | Contact your IFMS integration coordinator. More token requests will not fix a blocked subscription. |
| HTTP 302, or an HTML page instead of JSON | You posted to apim.kairosinnovations.dev. That host redirects into the Developer Portal. | Post to https://gw.kairosinnovations.dev/api/v1/ingest/telemetry. |
| HTTP 400 Bad Request | The request is not a valid batch: malformed JSON, a missing or null data, or a missing or empty positions. | Correct the request as a whole. A problem inside one position comes back as a 202 with a failure entry, not a 400. |
| HTTP 5xx | A temporary gateway or IFMS failure. | Keep the original positions. Retry with controlled exponential backoff and keep each recorded_at unchanged. |
| A TLS certificate error | A certificate, hostname or trust-store problem, or something intercepting the connection. | Stop and investigate. Never turn off certificate checks. |
HTTP 202 with positions not stored
A 202 means the gateway accepted your token and IFMS processed the batch. It does not mean every position was stored.
| What you see | What it means | What to do |
|---|---|---|
duplicates above 0 | You resent positions IFMS had already stored. | Nothing to fix. Avoid resending identical positions. |
rejected above 0 | Some positions failed validation or could not be stored. | Read each entry in failures. Fix or retry only those positions. |
Sending telemetry explains every failure reason and what to do about it.
FAQ
My token stopped working
Access tokens expire after the expires_in time in the token response. Request a new token with the same client credentials call, then continue. To avoid this, renew the token about 60 seconds before it expires. See Access tokens.
I get 401 even with a token
Check each of these:
- Your application is subscribed to IFMS-Telemetry-Ingest.
- You send the header exactly as
Authorization: Bearer <access_token>. - A token from Sandbox Keys gives 403 with
900901, not 401. See Every call returns 403 with900901. - If you just generated your keys, wait a little and try again. New keys can take a moment to become active.
If a new token and one retry still return 401, stop retrying and contact your IFMS integration coordinator.
Every call returns 403 with 900901, and my credentials are correct
You are using a token from Sandbox Keys. Read the Sandbox Keys warning, generate Production Keys and get a new token.
I get "403 — insufficient privileges" right after registering
Your account exists but is not approved yet. Wait for approval, then sign in again.
My POST returns a redirect or an HTML page instead of JSON
You are posting to apim.kairosinnovations.dev. That host is only the Developer Portal and the token endpoint. Send telemetry to https://gw.kairosinnovations.dev/api/v1/ingest/telemetry.
My positions come back as duplicates
IFMS spots duplicates by your provider identity, the normalised plate and recorded_at, compared to the microsecond. A safe retry keeps the original timestamp, so it appears in failures as DUPLICATE.
My request timed out. Can I send the batch again?
Yes. Resend the same positions with the same recorded_at values. Positions IFMS already stored come back as DUPLICATE, and nothing is stored twice.
Some positions are rejected
Read each entry in failures. Check the required fields, the coordinate ranges and the data types. Check that recorded_at is no more than 30 days old and no more than 5 minutes ahead.
My plate is not verified in the vehicle registry yet
IFMS can still accept the telemetry. It registers a plate it has not seen before as unverified and checks it against the registry later, in the background.
Do I ever send my provider code?
No. The gateway takes your provider identity from your approved application. Do not send it in the JSON body or in any header.