Operations

Error Codes

All Plurence API errors return a structured JSON body. Use message_code for programmatic handling.

Error response shape

json

{
  "error_id":     "DAT030002",        // Stable code for support reference
  "status_code":  404,
  "message_code": "NOT_FOUND",        // Machine-readable — use this in code
  "message":      "Project not found",
  "request_id":   "3fa85f64-...",     // Include when contacting support
  "details": [                        // Present on VALIDATION_FAILED only
    { "field": "name", "message": "must not be empty" }
  ]
}

Error catalog

message_code	HTTP	Meaning
INTERNAL	500	Unexpected server error. Retry with exponential backoff. If persistent, contact support with request_id.
UNAUTHORIZED	401	Missing or invalid credentials. Check your API key or JWT token.
FORBIDDEN	403	Valid credentials but insufficient permissions. Check project access.
VALIDATION_FAILED	400	Request body failed schema validation. Check the details array for per-field messages.
BAD_REQUEST	400	Malformed request. Check query parameters or body structure.
ENTITY_REQUIRED	400	Required entity parameter missing from the request.
NOT_FOUND	404	Resource does not exist or is not accessible with your credentials.
ROUTE_NOT_FOUND	404	API path does not exist. Check the URL for typos.
METHOD_NOT_ALLOWED	405	HTTP method not supported for this endpoint.
CONFLICT	409	Resource already exists. Idempotency key or unique field collision.

Error ID format

The error_id field follows the pattern SVC + CLASS + SEQ:

Prefix	Class	Meaning
DAT	00	System / 5xx errors
DAT	02	Auth errors (401/403)
DAT	03	Data / client errors (4xx)

Always include the request_id when contacting support — it ties your request to our internal logs.

Handling errors in code

python

import httpx, time

def call_plurence(payload, retries=3):
    for attempt in range(retries):
        r = httpx.post(
            "https://gateway.plurence.com/v1/chat/completions",
            headers={"x-api-key": API_KEY},
            json=payload,
        )
        if r.status_code == 200:
            return r.json()
        err = r.json()
        code = err.get("message_code")
        if code in ("UNAUTHORIZED", "FORBIDDEN"):
            raise PermissionError(err["message"])
        if r.status_code == 500 and attempt < retries - 1:
            time.sleep(2 ** attempt)
            continue
        raise RuntimeError(f"{code}: {err['message']}")