Errors & Codes — OASIS Docs

The Response Envelope

Every OASIS API response — success or failure — is wrapped in the same envelope:

json

{
  "result":         null,
  "isError":        true,
  "isWarning":      false,
  "message":        "A username with that name already exists.",
  "detailedMessage": "Duplicate username: david"
}

🔴

Do not rely solely on HTTP status codes

OASIS returns HTTP 200 for many business-logic failures. Always inspect isError first before consuming result.

isError vs isWarning

Flag	Meaning	Action
`isError: false, isWarning: false`	Full success	Consume `result` normally
`isError: false, isWarning: true`	Partial success — something non-fatal happened	Consume `result`, surface `message` to the user if relevant
`isError: true`	Hard failure — `result` will be `null`	Show `message` to the user, do not consume `result`

Common Error Messages

message	Cause	Fix
A username with that name already exists.	Duplicate username on register or update	Prompt user to choose a different username
A avatar with that email already exists.	Duplicate email on register or update	Offer login or password-reset flow
Email has not been verified.	Login attempted before verification	Re-send verification email
Username or password is incorrect.	Bad credentials on authenticate	Show generic auth error to user
Unauthorized	Missing or expired JWT	Re-authenticate and retry with a fresh token
Avatar not found.	ID doesn't exist or was soft-deleted	Verify the avatar ID is correct
An unknown error has occurred.	Unhandled server exception	Check `detailedMessage`; report to OASIS support

HTTP Status Codes

Code	Meaning
`200`	Request was received and processed — check `isError` for outcome
`400`	Malformed request — missing required fields or invalid JSON
`401`	No or invalid Authorization header
`403`	Authenticated but not permitted (e.g. non-admin accessing admin endpoint)
`404`	Route not found — check the endpoint path
`500`	Unhandled server error — retry with backoff; contact support if persistent

Recommended Handling Pattern

javascript

async function oasisRequest(url, options = {}) {
  const res = await fetch(url, {
    ...options,
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${token}`,
      ...options.headers
    }
  });

  if (!res.ok) throw new Error(`HTTP ${res.status}`);

  const envelope = await res.json();

  if (envelope.isError) {
    throw new Error(envelope.message || 'OASIS error');
  }

  if (envelope.isWarning) {
    console.warn('[OASIS]', envelope.message);
  }

  return envelope.result;
}

← Previous

Search API

Architecture