Error Handling

Understand API error responses and implement robust error handling.

When an API request fails, Persly returns a JSON error response with a consistent structure.

Error Response Format

{
  "error": {
    "message": "Human-readable error description",
    "type": "invalid_request_error",
    "code": "model_not_found",
    "param": "model"
  }
}

Field	Type	Description
`message`	string	Human-readable explanation of what went wrong
`type`	string	Error category (see table below)
`code`	string	Machine-readable error code
`param`	string \| null	The parameter that caused the error, if applicable

Error Codes

400 — Bad Request

Code	Type	Description
`model_not_found`	`invalid_request_error`	The specified model does not exist
`missing_required_field`	`invalid_request_error`	A required field is missing from the request
`invalid_request`	`invalid_request_error`	The request body is malformed or contains invalid values
`batch_size_exceeded`	`invalid_request_error`	Embedding batch size exceeds 100 items
`documents_limit_exceeded`	`invalid_request_error`	Rerank document count exceeds 1,000

401 — Unauthorized

Code	Type	Description
`authentication_error`	`authentication_error`	The API key is missing, invalid, or revoked

403 — Forbidden

Code	Type	Description
`organization_suspended`	`permission_error`	Your organization has been suspended

429 — Too Many Requests

Code	Type	Description
`quota_exceeded`	`insufficient_quota`	Free tier credits are exhausted
`spending_limit_exceeded`	`rate_limit_error`	Monthly spending limit reached

500 — Server Error

Code	Type	Description
`internal_error`	`server_error`	An unexpected error occurred on our servers

Error Handling Examples

import requests

response = requests.post(
    "https://api.persly.ai/v1/chat/completions",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "model": "persly-chat-v1",
        "messages": [{"role": "user", "content": "Hello"}],
    },
)

if response.status_code != 200:
    error = response.json()["error"]
    print(f"Error [{error['code']}]: {error['message']}")
else:
    data = response.json()
    print(data["choices"][0]["message"]["content"])

const response = await fetch("https://api.persly.ai/v1/chat/completions", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "persly-chat-v1",
    messages: [{ role: "user", content: "Hello" }],
  }),
});

if (!response.ok) {
  const { error } = await response.json();
  console.error(`Error [${error.code}]: ${error.message}`);
} else {
  const data = await response.json();
  console.log(data.choices[0].message.content);
}

Retry Strategy

For transient errors (5xx), implement exponential backoff:

import time
import requests

def call_api(payload, max_retries=3):
    for attempt in range(max_retries):
        response = requests.post(
            "https://api.persly.ai/v1/chat/completions",
            headers={"Authorization": "Bearer YOUR_API_KEY"},
            json=payload,
        )
        if response.status_code < 500:
            return response

        wait = 2 ** attempt  # 1s, 2s, 4s
        time.sleep(wait)

    return response  # Return last response after all retries

Error Type	Retry?	Action
400 Bad Request	No	Fix the request parameters
401 Unauthorized	No	Check your API key
403 Forbidden	No	Contact support
429 Quota Exceeded	No	Upgrade plan or wait for reset
429 Spending Limit	No	Increase spending limit in dashboard
500 Server Error	Yes	Retry with exponential backoff

Error Handling

On this page