Errors¶

Every error response has the same shape:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "amount must be a positive integer",
    "details": { "field": "amount" }
  }
}

details is optional. The SDKs raise a typed error (OuraError, OuraException or *oura.Error) that exposes code, status and message.

Code	HTTP	What to do
`VALIDATION_ERROR`	400	Fix the request. `details` says which field.
`UNAUTHORIZED`	401	The key is missing, malformed or revoked.
`FORBIDDEN`	403	The key can't do this, for example a test key reading live data.
`NOT_FOUND`	404	No such payment for this key's mode.
`CONFLICT`	409	The payment's state doesn't allow this (such as cancelling a paid payment), or a request with the same idempotency key is still in progress.
`RATE_LIMITED`	429	Slow down and retry with backoff.
`INTERNAL`	500 / 502	Something failed on our side or at the rail. Retry with the same idempotency key.

The SDKs also define IDEMPOTENCY_CONFLICT and PROVIDER_ERROR for future use. Handle unknown codes by their HTTP status.

The SDKs also use CONNECTION_ERROR when they can't reach the API at all.

Handling errors¶

Node.jsPythonPHPGoJava.NETRuby

import { OuraError } from '@oura/sdk';

try {
  await oura.payments.create({ amount: -1, methods: ['esewa'] });
} catch (e) {
  if (e instanceof OuraError) console.error(e.code, e.status, e.message);
}

from oura.errors import OuraError

try:
    oura.payments.create({"amount": -1, "methods": ["esewa"]})
except OuraError as e:
    print(e.code, e.status, e.message)

try {
    $oura->payments->create(['amount' => -1, 'methods' => ['esewa']]);
} catch (Oura\OuraError $e) {
    echo $e->errorCode . ' ' . $e->status . ' ' . $e->getMessage();
}

var oerr *oura.Error
if errors.As(err, &oerr) {
    log.Printf("%s %d: %s", oerr.Code, oerr.Status, oerr.Message)
}

} catch (OuraException e) {
    log.error("{} {} {}", e.getCode(), e.getStatus(), e.getMessage());
}

catch (OuraException e)
{
    logger.LogError("{Code} {Status} {Message}", e.Code, e.Status, e.Message);
}

rescue Oura::Error => e
  puts "#{e.code} #{e.status} #{e.message}"