Errors and Error Handling

This page contains information about the errors our API may return and guidance on how to handle them gracefully in your integration.

When something goes wrong, the Thrive API returns structured JSON errors to help you quickly identify the issue, understand what happened, and take the right corrective action.

Error Response Format

Every error is returned in a consistent JSON object containing the HTTP status code, a generalised error phrase, and a detailed, human-readable message.

Field	Description
`status`	The HTTP response code (e.g., 400, 404).
`error`	A general error phrase (e.g., "Bad Request").
`message`	A human-readable explanation specific to the request.

For example:

{
  "status": 400,
  "error": "Bad Request",
  "message": "string"
}

Note:
Use the status field to drive programmatic handling, and the message field to surface context in your logs or UI.

Common Error Codes

HTTP Status	Type	Description	Suggested Fix
400	`invalid_request`	Missing or invalid parameters in the request body or URL.	Verify required fields and data types.
401	`unauthorized`	API key is missing, invalid, or improperly formatted.	Check your API key and headers.
403	`forbidden`	Insufficient permissions for the given resource or action.	Confirm your key has the necessary scopes.
404	`not_found`	The requested resource (e.g., a specific user or course) does not exist.	Double-check endpoint and resource ID.
409	`conflict`	The request cannot be completed due to a conflicting resource state (e.g., trying to create a resource that already exists).	Resolve the data conflict before retrying.
422	`unprocessable_entity`	Validation of the request data failed due to semantic errors.	Inspect the `message` for validation details.
429	`rate_limit_exceeded`	Too many requests sent in a short period.	Wait and retry using a backoff strategy.
500	`server_error`	An internal server issue occurred.	Retry later; contact support if the issue persists.

Tips for Robust Error Handling

Log the entire error response for debugging purposes.
Don’t retry all errors automatically. Only retry 429 (Rate Limit Exceeded) or 5xx codes (Server Errors).
Show friendly, localised messages to end-users, not raw API responses.
Handle network failures (e.g., connection timeouts) separately from API-level errors.
Monitor for recurring 4xx errors — they often indicate a deeper integration logic issue.

Handling Errors Gracefully

Here are suggestions on how to handle non-successful HTTP responses programmatically:

try {
  const res = await fetch('{API_BASE_URL}/users', {
    headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
  });
  
  if (!res.ok) {
    const error = await res.json();
    console.error(`Error ${error.error.status}: ${error.error.message}`);
  }
} catch (err) {
  console.error('Network error:', err);
}

import requests

response = requests.get("{API_BASE_URL}/users", headers={"Authorization": "Bearer YOUR_API_KEY"})

if response.status_code != 200:
    error = response.json().get("error", {})
    print(f"Error {error.get('status')}: {error.get('message')}")

if (response.statusCode() >= 400) {
    JSONObject err = new JSONObject(response.body()).getJSONObject("error");
    System.out.println("Error " + err.getInt("status") + ": " + err.getString("message"));
}