Error Handling

All API responses follow a consistent format and use appropriate HTTP status codes.

Error Response Format

For proper error handling, you should check both:

1. The HTTP status code (2xx for success, 4xx for client errors, 5xx for server errors)
2. The presence of an error message in the response body

Standard Error Response:

{
  "data": null,
  "meta": {},
  "error": "Error message here"
}

Common Status Codes

Status Code	Error Message	Description
`400`	`"Invalid cursor format"`	The pagination cursor is malformed
`401`	`"Unauthorized"`	Missing or invalid API key
`404`	`"Entry type not found"`	The specified entry type doesn't exist
`404`	`"Entry not found"`	The specified entry doesn't exist
`404`	`"Scribe not found"`	The specified scribe doesn't exist
`500`	`"Internal server error"`	An unexpected server error occurred

Error Handling Examples

Example 1: Not Found Error

curl -i -X GET "https://obelisk.li/api/v1/entries/non-existent-id" \
     -H "X-Api-Key: your_api_key_here"

HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "data": null,
  "meta": {},
  "error": "Entry not found"
}

Example 2: Unauthorized Error

curl -i -X GET "https://obelisk.li/api/v1/entries/entry-id" \
     -H "X-Api-Key: invalid_key"

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "data": null,
  "meta": {},
  "error": "Unauthorized"
}

Example 3: JavaScript Error Handling

async function fetchEntry(id) {
  const response = await fetch(`/api/v1/entries/${id}`, {
    headers: { 'X-Api-Key': 'your_api_key_here' }
  });
  
  const data = await response.json();
  
  if (!response.ok) {
    // Handle error based on status code and error message
    throw new Error(`${response.status}: ${data.error}`);
  }
  
  return data.data; // Return the entry data on success
}

// Usage
try {
  const entry = await fetchEntry('entry-id');
  console.log('Entry:', entry);
} catch (error) {
  console.error('Failed to fetch entry:', error.message);
}

Example 4: Python Error Handling

import requests

def fetch_entry(entry_id, api_key):
    url = f"https://obelisk.li/api/v1/entries/{entry_id}"
    headers = {"X-Api-Key": api_key}
    
    response = requests.get(url, headers=headers)
    
    if response.status_code == 200:
        return response.json()["data"]
    else:
        error_data = response.json()
        raise Exception(f"{response.status_code}: {error_data['error']}")

# Usage
try:
    entry = fetch_entry("entry-id", "your_api_key_here")
    print("Entry:", entry)
except Exception as err:
    print(f"Failed to fetch entry: {err}")

← Previous: Scribe Chat