API Documentation

Error Handling

This section describes the errors returned by the Oura API. The Oura API responds to requests with the appropriate HTTP status code. The response format is based on RFC7807 for all requests. Additionally, requests related to OAuth2 also include the error response fields as defined in RFC6749.

  1. Standard HTTP Error Response
  2. OAuth2 Error Response

HTTP status codes:

  • 2xx: Successful request.
  • 4xx: There was some problem with your request.
  • 5xx: Server error.

Standard Error Response Fields

In case of an error, all Oura API endpoints respond with a JSON object that contains at least the following fields.
Field Always Provided? Description
status Always The HTTP status code generated by the origin server. Typically 400-599.
title Always A short, human-readable summary of the problem type.
detail Optional A human-readable explanation specific to this occurrence of the problem.
Fig.1 - Error response fields.

    "status": 400,
    "title": "something is wrong",
    "detail": "This provides more information"  
Fig.2 - An example error response.

Common HTTP Errors

  • Invalid Access token

    Access token not provided or is invalid. Check that you are including a token and it is complete.
  • Token Already Used Or Revoked

    Token already used or revoked. If you are trying to use a refresh token, note that it can only be used once.
  • Expired Token

    Token has expired.
  • Missing Scopes

    Missing required scopes. Your token must have the scopes listed as part of the detail of the error. You may need to have the user re-authenticate your app with the required scopes.
  • Invalid Token

    Token not provided. Either token is not provided at all or is invalid.
  • No Valid Redirect URIs In Application

    No redirect URIs set in the application. Check that your application has at least one valid redirect_uri.
  • Missing Redirect URI Parameter

    Missing redirect_uri parameter. Provide a redirect_uri as a query parameter.
  • Redirect URI Not Found

    redirect uri not found in application redirect URIs. Provide a redirect_uri that exists in your application.
  • Invalid Client ID

    Invalid client_id. Check that your client_id is correct and valid.
  • Invalid Grant Type

    Invalid grant_type. grant_type must be either authorization_code or refresh_token.
  • Missing Redirect URI Payload

    redirect_uri missing. Check that redirect_uri payload is provided.
  • Redirect URI Does Not Match

    redirect_uri does not match. The redirect_uri payload must match that of the authorization_code.
  • Request Rate Limit Exceeded

    The API V1 and V2 API are rate limited to 5000 requests in a 5 minute period. You will receive a 429 error code if you exceed this limit. Contact us if you expect your usage to exceed this limit.

OAuth2 Error Response Fields

When returning an error from an OAuth2 endpoint, the Oura API responds with a JSON object that contains the following fields in line with RFC6749 in addition to the RFC7807-inspired fields mentioned above.
Field Always Provided? Description
error Always standard OAuth2 error code which can be one of the following: invalid_request, unauthorized_client, access_denied, unsupported_response_type, invalid_scope, invalid_token, unsupported_grant_type, server_error or temporarily_unavailable
error_description Optional Human-readable description that provides additional information.
error_uri Optional A URI identifying a human-readable web page with information about the error.
Fig.3 - OAuth2 Error response fields.

    "status": 401,
    "title": "Invalid Access Token",
    "error": "invalid_token",
    "error_description": "Access token not provided or is invalid.",
    "detail": "Access token not provided or is invalid.",
Fig.4 - An example of OAuth2 error response.

OAuth2 Error Field

  • invalid_request

    The request is missing a required parameter, includes an unsupported parameter value (other than grant type), repeats a parameter, includes multiple credentials, utilizes more than one mechanism for authenticating the client, or is otherwise malformed.
  • invalid_client

    Client authentication failed (e.g., unknown client, no client authentication included, or unsupported authentication method).
  • invalid_grant

    The provided authorization grant (e.g., authorization code, resource owner credentials) or refresh token is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client.
  • unauthorized_client

    The client is not authorized by Oura server to make the request.
  • unsupported_grant_type

    The authorization grant type you have provided is not supported by Oura authorization server.
  • invalid_scope

    The scope you have requested is invalid, unknown, malformed, or exceeds the scope granted by the Oura API.
  • invalid_token

    The access token provided is expired, revoked, malformed, or invalid.