Response

Understanding API responses and error handling

Response Format

All API responses follow a consistent, type-safe format that makes error handling straightforward.

Type Safety: When response.ok is true, the data field is guaranteed to be defined. When response.ok is false, the data field will not be defined. This pattern enables type-safe response handling.

Response Structure

Every API response includes an ok field that indicates success or failure:

Success Response:

{
  "ok": true,
  "code": 200,
  "message": "Success",
  "data": { ... }
}

Error Response:

{
  "ok": false,
  "code": 400,
  "message": "Error description"
}

Pagination: endpoints that support keyset pagination (e.g. accounts.getAccounts(), posts.getPosts()) include an additional nextCursor field alongside data when a limit was passed — pass it back as cursor to fetch the next page. See each endpoint’s reference page for details.

Using the Response Pattern

The ok field allows you to easily check if the request succeeded:

const response = await client.accounts.getAccounts();

if (response.ok) {
  // Success - data is available
  console.log(response.data);
  response.data.forEach(account => {
    console.log(account.username);
  });
} else {
  // Error - handle the error
  console.error(`Error ${response.code}: ${response.message}`);
}

response = requests.post(
    'https://api.ugc.inc/accounts',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    json={}
)

data = response.json()

if data['ok']:
    # Success - data is available
    print(data['data'])
else:
    # Error - handle the error
    print(f"Error {data['code']}: {data['message']}")

HTTP Status Codes

Common status codes you may encounter:

• 200 - Success
• 400 - Bad Request (invalid parameters)
• 401 - Unauthorized (invalid, missing, or expired API key)
• 403 - Forbidden (the key is valid but lacks the required scope, or is not bound to that resource)
• 404 - Not Found (resource doesn’t exist)
• 500 - Internal Server Error