Skip to main content

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 seeLikely causeWhat to do
HTTP 401 with invalid_clientThe 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_tokenAn unexpected token response.Stop. Contact your IFMS integration coordinator. Note only the HTTP status and the error code.
HTTP 5xxA temporary failure of the token service.Retry with controlled exponential backoff. Do not rotate your credentials automatically.
A TLS certificate errorA 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 seeLikely causeWhat to do
HTTP 401 Unauthorized, gateway code 900902The 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 900901The token came from Sandbox Keys. The provider 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 900901Your 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 JSONYou 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 RequestThe 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 5xxA temporary gateway or IFMS failure.Keep the original positions. Retry with controlled exponential backoff and keep each recorded_at unchanged.
A TLS certificate errorA 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 seeWhat it meansWhat to do
duplicates above 0You resent positions IFMS had already stored.Nothing to fix. Avoid resending identical positions.
rejected above 0Some positions failed the legality check or 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 FMS Service Provider Integration API.
  • 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 with 900901.
  • 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 has no IFTMS answer yet​

IFMS stores a position only when IFTMS, the Ministry’s vehicle register, says the vehicle is legal. Refused positions are never stored. For each refusal, the HTTP 202 response lists an entry in failures[] with outcome: REJECTED and a reason. A new plate is first refused as VEHICLE_NOT_CHECKED while IFMS asks IFTMS in the background. Send it again later.

ReasonWhat it meansWhat to do
VEHICLE_NOT_REGISTEREDIFTMS has no record of the plate. A plate longer than 20 characters is also refused with this reason.Stop sending positions for it, or have the vehicle registered in IFTMS.
VEHICLE_NOT_LEGALIFTMS says the vehicle is not legal, including a vehicle removed from the register.Stop sending positions until IFTMS says the vehicle is legal.
VEHICLE_NOT_CHECKEDIFMS has no IFTMS answer yet for this plate.Send the position again later, with its original recorded_at.

My positions are refused as PLATE_HELD_BY_ANOTHER_PROVIDER​

Another provider reported this plate first, and IFMS accepts one provider per plate. The message names that provider and the date it took the plate. The hold ends when IFTMS records a change of operator or removes the vehicle, or after 30 days without positions from the holding provider. If the vehicle has moved to you, ask the Ministry of Transport and Logistics to correct its record in IFTMS, quoting the plate. See One provider per plate.

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.