Errors & Status Codes

The Logimeter API uses standard HTTP status codes to signal the outcome of every request. Error responses always return a JSON body so your integration can parse and handle them programmatically.

Overview

Successful requests return 2xx status codes. Client errors return 4xx codes. Server errors return 5xx codes. In all error cases the response body is a JSON object describing what went wrong.

Error Response Format

Logimeter uses Django REST Framework (DRF) as its API layer. Three distinct error body shapes are used depending on the type of error:

Standard detail error

Used for authentication failures, permission denials, and general errors where a single human-readable message is appropriate.

{
  "detail": "Error message describing what went wrong."
}

{
  "detail": "Authentication credentials were not provided."
}

{
  "detail": "Not found."
}

Validation error

Used for 400 Bad Request responses when one or more submitted fields fail validation. The response object maps each failing field name to a list of error messages. Non-field errors (those that apply to the request as a whole rather than a single field) are keyed under non_field_errors.

{
  "field_name": ["Error message for this field."],
  "another_field": ["First error.", "Second error."],
  "non_field_errors": ["Error that applies to the whole request."]
}

{
  "caller_id": [
    "Enter a valid phone number in E.164 format (e.g. +27831234567)."
  ]
}

{
  "username": ["This field is required."],
  "password": ["This field is required."]
}

Blocklist error

Certain endpoints — particularly the Blocklist API — return a flat error key with a longer descriptive message that includes context such as entity identifiers.

{
  "error": "Detailed error message with context."
}

{
  "error": "Entity 'example-entity-uuid' is not owned by the authenticated partner and cannot be modified."
}

HTTP Status Code Reference

Common Errors by Product

Certain products have specific error conditions worth noting when building your integration:

Dynamic Number Allocation (DNA)

Connect

Call Manager

Blocklist

Validation Error Example

The following example shows a real validation error response returned when a phone number is submitted in an incorrect format. The caller_id field expects E.164 format (e.g. +27831234567).

curl -X POST https://next.logimeter.com/v1/connect/ \
  -H "Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b" \
  -H "Content-Type: application/json" \
  -d '{
    "caller_id": "0831234567",
    "reference": "lead-001"
  }'

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "caller_id": [
    "Enter a valid phone number in E.164 format (e.g. +27831234567)."
  ]
}

Handling Errors in Code

The pattern below shows a robust approach to catching and classifying API errors in both JavaScript and Python.

async function callApi(url, options = {}) {
  const response = await fetch(url, {
    ...options,
    headers: {
      'Authorization': `Token ${process.env.LOGIMETER_API_TOKEN}`,
      'Content-Type': 'application/json',
      ...options.headers,
    },
  });

  if (response.ok) {
    // 204 No Content has no body
    return response.status === 204 ? null : response.json();
  }

  let errorBody;
  try {
    errorBody = await response.json();
  } catch {
    errorBody = { detail: response.statusText };
  }

  switch (response.status) {
    case 400:
      // Validation errors — errorBody may contain per-field messages
      console.error('Validation error:', errorBody);
      throw new Error(`Bad request: ${JSON.stringify(errorBody)}`);
    case 401:
      console.error('Authentication failed — check your API token.');
      throw new Error(errorBody.detail);
    case 403:
      console.error('Permission denied:', errorBody.detail);
      throw new Error(errorBody.detail);
    case 404:
      console.error('Resource not found:', errorBody.detail);
      throw new Error(errorBody.detail);
    default:
      throw new Error(`API error ${response.status}: ${JSON.stringify(errorBody)}`);
  }
}

import os
import requests

session = requests.Session()
session.headers['Authorization'] = f'Token {os.environ["LOGIMETER_API_TOKEN"]}'

def call_api(method, path, **kwargs):
    url = f'https://next.logimeter.com{path}'
    response = session.request(method, url, **kwargs)

    if response.ok:
        # 204 No Content has no body
        return None if response.status_code == 204 else response.json()

    try:
        error_body = response.json()
    except ValueError:
        error_body = {'detail': response.text}

    if response.status_code == 400:
        # Validation errors — error_body may contain per-field messages
        raise ValueError(f'Validation error: {error_body}')
    elif response.status_code == 401:
        raise PermissionError(f'Authentication failed: {error_body.get("detail")}')
    elif response.status_code == 403:
        raise PermissionError(f'Permission denied: {error_body.get("detail")}')
    elif response.status_code == 404:
        raise LookupError(f'Resource not found: {error_body.get("detail")}')
    else:
        response.raise_for_status()

For integration and token prerequisites, see Integration. For pagination behaviour on list endpoints, see Pagination.