Error Reference

Token exchange errors

These errors are returned when the token exchange request fails.

Error Code	HTTP Status	Description	How to fix
`TokenExchange.InvalidGrantType`	400	`grantType` is not the expected value	Set `grantType` to exactly `urn:ietf:params:oauth:grant-type:jwt-bearer`
`TokenExchange.InvalidFormat`	400	The assertion is not a valid JWT	Check that your assertion is a properly encoded JWT string
`TokenExchange.MissingKid`	400	JWT header is missing `kid` or it is not a valid UUID	Add your API Key ID as the `kid` field in the JWT header
`TokenExchange.KeyNotFound`	400	No API key found for the given `kid`	Verify your API Key ID in the Partner Portal
`TokenExchange.KeyExpired`	400	The API key has expired	Register a new public key in the Partner Portal
`TokenExchange.PartnerInactive`	400	Your partner account is not active	Contact RynoPay support
`TokenExchange.InvalidSignature`	400	JWT signature verification failed	Ensure you are signing with the private key that matches the registered public key
`TokenExchange.AssertionTooLong`	400	JWT lifetime exceeds 5 minutes	Set `exp` to no more than 300 seconds after `iat`
`TokenExchange.SubMismatch`	400	`sub` claim does not match `iss`	Both `iss` and `sub` must be set to your Partner ID
`TokenExchange.MissingJti`	400	JWT is missing the `jti` claim	Add a unique `jti` value (UUID recommended)
`TokenExchange.ReplayDetected`	400	This `jti` has already been used	Generate a new unique `jti` for every request
`TokenExchange.KeyError`	400	Stored public key could not be loaded	Contact RynoPay support -- this is a server-side configuration issue

These errors may be returned when calling any RynoPay API endpoint.

HTTP Status	Description	How to fix
401 Unauthorized	Access token is missing, invalid, or expired	Perform a new token exchange to get a fresh access token
403 Forbidden	Insufficient scope for this endpoint	Request the required scope in your token exchange
429 Too Many Requests	Rate limit exceeded	Wait and retry. See Rate Limits

All error responses follow this structure:

{
  "isSuccess": false,
  "error": {
    "code": "TokenExchange.InvalidSignature",
    "message": "JWT assertion signature validation failed"
  }
}

Make sure the private key you are signing with matches the public key registered in the Partner Portal.
Verify you are using the correct kid (API Key ID). If you have multiple keys, you may be using the wrong one.
Check that your JWT library is using ES256 (not RS256 or another algorithm).

Your jti must be globally unique. If you are restarting your application and generating jti values from a counter, switch to UUID v4.
Check your server clock -- if iat is in the past and the jti was already used in a previous session, this error will occur.

The validation checks exp - iat, not exp - now. Make sure iat is set to the current time, not a time in the past.

If you cannot resolve an error, contact the RynoPay partner support team with: