Error Handling

Error Response Format

All API errors return a JSON object with an error field containing a human-readable message:

{
  "error": "Resource not found"
}

Validation Errors

When request validation fails (invalid body, query params, or path params), the API returns a 400 status with field-level details:

{
  "error": "Validation failed",
  "details": {
    "formErrors": [],
    "fieldErrors": {
      "name": ["Required"],
      "unit_price": ["Expected number, received string"]
    }
  }
}

Field	Type	Description
formErrors	string[]	Errors that apply to the entire request body
fieldErrors	Record<string, string[]>	Per-field validation errors, keyed by field name

HTTP Status Codes

Success Codes

Status	Meaning	Used When
200 OK	Request succeeded	GET, PATCH, DELETE operations
201 Created	Resource created	POST operations that create a new resource

Error Codes

Status	Meaning	Used When
400 Bad Request	Invalid input	Validation failure, invalid UUID format, missing required fields
401 Unauthorized	Authentication required	No token provided or token is invalid/expired
403 Forbidden	Insufficient permissions	Valid token but insufficient access for this operation
404 Not Found	Resource does not exist	Requesting a resource ID that does not exist, or unknown URL path
409 Conflict	Duplicate resource	Creating a resource that violates a unique constraint
500 Internal Server Error	Unexpected failure	Unhandled server errors

Common Error Scenarios

Duplicate Resource (409)

Returned when creating a resource that would violate a uniqueness constraint.

curl -X POST https://api.getadva.ai/api/v1/core/products \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Premium Lawn Treatment", "category": "turf"}'

{
  "error": "Resource already exists",
  "code": "23505"
}

Related Resource Not Found (400)

Returned when referencing a related record that does not exist.

curl -X POST https://api.getadva.ai/api/v1/ops/jobs \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"customer_id": "00000000-0000-0000-0000-000000000000"}'

{
  "error": "Referenced resource not found",
  "code": "23503"
}

Resource Not Found (404)

Returned when querying by ID and no matching record exists.

curl -X GET https://api.getadva.ai/api/v1/core/customers/00000000-0000-0000-0000-000000000000 \
  -H "Authorization: Bearer $TOKEN"

{
  "error": "Customer not found"
}

Invalid UUID Format

All resource IDs must be valid UUIDs. Passing a malformed ID returns a validation error:

{
  "error": "Validation failed",
  "details": {
    "formErrors": [],
    "fieldErrors": {
      "id": ["Invalid uuid"]
    }
  }
}

Missing Required Fields

Omitting required fields from a POST request:

{
  "error": "Validation failed",
  "details": {
    "formErrors": [],
    "fieldErrors": {
      "name": ["Required"]
    }
  }
}

Best Practices

1. Always check the status code before parsing the response body. Any non-2xx status indicates an error.
2. Handle validation errors by inspecting details.fieldErrors to show per-field messages in your UI.
3. Retry on 500 errors with exponential backoff — these are typically transient.
4. Do not retry 4xx errors without fixing the request. These indicate a problem with your input.