Errors

The Addis AI API uses standard HTTP response codes to indicate the success or failure of an API request.

In general:

2xx indicates success.
4xx indicates an error that failed given the information provided (e.g., a required parameter was omitted, or a key was invalid).
5xx indicates an error with Addis AI's servers.

Error Object

When an error occurs, the API returns a JSON object with a detailed message and a machine-readable code.

{
    "status": "error",
    "error": {
        "code": "invalid_api_key",
        "message": "Invalid or expired API key."
    }
}

Prop

Type

HTTP Status Codes

Code	Status	Meaning
200	OK	Everything worked as expected.
400	Bad Request	The request was unacceptable, often due to missing a required parameter.
401	Unauthorized	No valid API key provided.
403	Forbidden	The API key doesn't have permissions to perform the request.
404	Not Found	The requested resource (e.g., Model ID) doesn't exist.
429	Too Many Requests	You have hit your rate limit or quota.
500	Server Error	Something went wrong on Addis AI's end.
503	Service Unavailable	The engine is currently overloaded. Please retry.

Handling Errors Programmatically

You should wrap your API calls in a try/catch block to handle exceptions gracefully.

import AddisAI from "addisai";

const addis = new AddisAI();

try {
  const response = await addis.chat.completions.create({
    messages: [{ role: "user", content: "ሰላም" }],
  });
  console.log(response.choices[0].message.content);
} catch (error) {
  const status =
    typeof error === "object" && error !== null && "status" in error
      ? error.status
      : undefined;

  if (status === 429) {
    // Retry with bounded exponential backoff and jitter.
  } else {
    throw error;
  }
}

from addisai import AddisAI

addis = AddisAI()

try:
    response = addis.chat.completions.create(
        messages=[{"role": "user", "content": "ሰላም"}],
    )
    print(response["choices"][0]["message"]["content"])
except Exception as error:
    status = getattr(error, "status", None)
    if status == 429:
        # Retry with bounded exponential backoff and jitter.
        pass
    else:
        raise

Common Issues

401 Unauthorized

Cause: Your X-API-Key header is missing or incorrect.

Fix: Ensure there are no extra spaces in your key. Check if you accidentally revoked the key in the dashboard.

400 Bad Request

Cause: Invalid JSON format or missing required fields (like target_language).

Fix: Validate your JSON structure. Ensure request_data is stringified when using multipart forms.

429 Rate Limit

Cause: You are sending requests too fast for your plan (e.g., >60 RPM on Free).

Fix: Implement exponential backoff (wait and retry). Contact sales to increase limits.

500 / 503 Errors

Cause: Temporary issue with the Addis AI inference engine or heavy load.

Fix: Retry the request after a short delay. If the issue persists, check our status page.