caret

Troubleshooting

Authorisation errors

I see a 500 error screen when trying to start the authorization flow

Pay attention to the error message displayed on the screen. This will happen if any of the parameters are incorrectly set on your authorize url e.g.

  • The redirect_uri doesn’t match one of the Redirect URIs saved against your app on developer.xero.com
  • You’ve requested an invalid scope
  • Your client_id isn’t correct

Authentication Unsuccessful

The Xero-tenant-id header is missing, incorrect or isn't authorized for use with this access token. This could be because:

  • The user has revoked access
  • User permissions changed: if the user who has authorized the connection between the API application and the Xero tenant is removed from accessing that tenant, or their role changes so that they can longer authorize API connections, then the connection will no longer be authorized
  • The tenant is no longer active. This generally occurs when an organisation has been deleted, the free trial has ended or a demo organisation has been reset.
{
"title": "Forbidden",
"status": 403,
"detail": "AuthenticationUnsuccessful",
"instance": "65e420cd-796c-493b-8f52-5eae2ee667ce"
}

Access token request errors

Invalid client

If the client_id or client_secret you pass in are incorrect then you will receive this response.

{
    "error": "invalid_client"
}

To solve this error, make sure you have the correct credentials for your app. Double check your client id in My Apps and try generating a new secret if required.

Unsupported grant type

If you don't pass in a grant_type of authorization_code then you will get this response.

{
    "error": "unsupported_grant_type"
}

To solve this error, include grant_type=authorization_code as a parameter in the body.

Invalid grant

You might get this error for a number of reasons

  • The code provided is incorrect, expired or has already been used
{
    "error": "invalid_grant"
}

The only way to solve this error is to get the user to re-authorize so you can get a new authorization code.

Unauthorized client

  • The callback_uri provided when requesting an access token doesn't match the one used when requesting the code.
{
    "error": "unauthorized_client"
}

TLS errors

Access Denied

All API communication using OAuth 2.0 requires TLS 1.2 or higher. Any requests using TLS 1.1 or lower will receive a 403 Forbidden error with the following html in the response body:

<HTML>

<HEAD>
    <TITLE>Access Denied</TITLE>
</HEAD>

<BODY>
    <H1>Access Denied</H1>

    You don't have permission to access "https://api.xero.com..." on this server.<p>
    Reference...
</BODY>

</HTML>