Skip to main content
Thought Industries Developer Hub
https://.thoughtindustries.com

Status codes

HTTP status codes returned by the Thought Industries REST API and how to handle them.

Status codes

The REST API uses standard HTTP status codes to indicate the outcome of each request. Successful operations return 2xx codes, client errors return 4xx, and server errors return 5xx.

Success codes

CodeMeaningWhen returned
200 OKRequest succeededGET, PUT, PATCH requests that return data
201 CreatedResource createdPOST requests that create a new resource
204 No ContentRequest succeeded, no bodyDELETE requests and updates with no response body

Redirect codes

CodeMeaningWhen returned
301 Moved PermanentlyResource permanently movedFollow the Location header
304 Not ModifiedResource unchanged since last requestUse your cached version

Client error codes

CodeMeaningAction
400 Bad RequestMalformed request body or invalid parametersCheck request syntax and parameter types
401 UnauthorizedMissing or invalid authenticationVerify your API key in the Authorization header
403 ForbiddenValid credentials but insufficient permissionsCheck the role assigned to your API key
404 Not FoundResource does not existVerify the resource ID and endpoint path
405 Method Not AllowedHTTP method not supportedUse the correct method for this endpoint
409 ConflictResource state conflict (e.g., duplicate)Check for existing resources before creating
422 Unprocessable EntityValid syntax but semantic errorsReview field values against validation rules
429 Too Many RequestsRate limit exceededImplement retry with backoff (see rate limits)

Server error codes

CodeMeaningAction
500 Internal Server ErrorUnexpected server failureRetry after a brief delay; contact support if persistent
502 Bad GatewayUpstream service unavailableRetry with exponential backoff
503 Service UnavailableTemporary maintenance or overloadCheck the Retry-After header
504 Gateway TimeoutUpstream server timeoutRetry with exponential backoff

Error response format

All error responses follow a consistent JSON structure:

Response: 422 Unprocessable Entity

{
  "error": "validation_error",
  "message": "Request body contains invalid fields.",
  "details": [
    {
      "field": "email",
      "code": "invalid_format",
      "message": "Must be a valid email address."
    },
    {
      "field": "firstName",
      "code": "required",
      "message": "This field is required."
    }
  ]
}

Error fields

Error response body

FieldTypeRequiredDescription
errorstringYesMachine-readable error code for programmatic handling.
messagestringYesHuman-readable summary of the error.
detailsarrayNoField-level validation errors. Present only for 400 and 422 responses.

Handling errors in code

response=$(curl -s -w "\n%{http_code}" \
  -H "Authorization: Bearer ti_live_a1b2c3d4e5f6g7h8i9j0" \
  "https://api.thoughtindustries.com/incoming/v2/users/nonexistent")

http_code=$(echo "$response" | tail -1)
body=$(echo "$response" | sed '$ d')

if [ "$http_code" -ge 400 ]; then
  echo "Error $http_code: $body"
fi
const response = await fetch(url, { headers });

if (!response.ok) {
  const error = await response.json();
  console.error(`[${response.status}] ${error.message}`);

  if (error.details) {
    error.details.forEach(d => console.error(`  ${d.field}: ${d.message}`));
  }
}
response = requests.get(url, headers=headers)

if not response.ok:
    error = response.json()
    print(f"[{response.status_code}] {error['message']}")

    for detail in error.get("details", []):
        print(f"  {detail['field']}: {detail['message']}")
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);

if ($httpCode >= 400) {
    $error = json_decode($response, true);
    echo "[{$httpCode}] {$error['message']}\n";

    foreach ($error['details'] ?? [] as $detail) {
        echo "  {$detail['field']}: {$detail['message']}\n";
    }
}

Related