Skip to main content
When a request fails, the Wraith API always returns a JSON body alongside the appropriate HTTP status code. Parsing this body gives you a machine-readable status code and a human-readable message explaining what went wrong.

​
Error response format

All errors share the same shape: 
{
  message: string;    // human-readable description
  statusCode: number; // mirrors the HTTP status code
}
Example error body
{
  "message": "Name 'alice' is already registered",
  "statusCode": 409
}

​
HTTP status codes

StatusNameWhen it occurs
400Bad RequestMissing or invalid parameters — e.g., malformed agent name, invalid signature
401UnauthorizedMissing or invalid API key
404Not FoundThe requested agent, invoice, or conversation does not exist
409ConflictA unique constraint was violated — e.g., the .wraith name is already taken
500Internal Server ErrorAn unexpected server-side failure

​
Status code details

​
400 Bad Request

The request body or path parameters failed validation. Check the message field for the specific constraint that failed.
400 example
{
  "message": "Name must be 3-32 characters, lowercase alphanumeric and hyphens only",
  "statusCode": 400
}
Common causes:
  • Agent name contains uppercase letters, spaces, or special characters
  • Missing required fields (name, chain, wallet, signature)
  • Signature format is invalid or does not match the expected scheme

​
401 Unauthorized

The Authorization header is missing, malformed, or contains an invalid key.
401 example
{
  "message": "Invalid API key",
  "statusCode": 401
}
Fix: Verify your key is prefixed with wraith_live_ and is being sent as Bearer wraith_live_.... See Authentication for the correct header format.

​
404 Not Found

The resource you requested does not exist, or it belongs to a different API key.
404 example
{
  "message": "Agent not found",
  "statusCode": 404
}
Common causes:
  • Incorrect agent ID, invoice ID, or conversation ID in the path
  • The resource was deleted
  • The resource exists but belongs to a different account

​
409 Conflict

A uniqueness constraint was violated. Most commonly, you tried to register a .wraith name that is already taken.
409 example
{
  "message": "Name 'alice' is already registered",
  "statusCode": 409
}
Fix: Choose a different name, or look up the existing agent with GET /agent/info/:name to confirm ownership.

​
500 Internal Server Error

An unexpected error occurred on the server. These are rare. If the problem persists, check the Wraith status page.
500 example
{
  "message": "Internal server error",
  "statusCode": 500
}

​
Handling errors in code

import { Wraith, Chain } from "@wraith-protocol/sdk";

const wraith = new Wraith({ apiKey: process.env.WRAITH_API_KEY! });

try {
  await wraith.createAgent({
    name: "alice",
    chain: Chain.Horizen,
    wallet: "0xYourWallet",
    signature: "0x...",
  });
} catch (err) {
  // err.message comes directly from the server's `message` field
  console.error(err.message); // "Name 'alice' is already registered"
}