Error Codes

All DomeAgent API errors follow a consistent format. When a request fails, the response body contains an error object with a machine-readable code and a human-readable message.

Error Response Format

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters."
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-01-15T10:30:00.000Z"
  }
}

Error Code Reference

Code	HTTP	Description
`VALIDATION_ERROR`	400	The request body or query parameters are invalid. Check the message field for details on which parameter failed validation.
`INVALID_URL`	400	A URL provided in the request (e.g. image_url) is not a valid HTTP/HTTPS URL.
`UNAUTHORIZED`	401	The request is missing a valid API key, or the provided key is invalid or expired. Include your key in the X-API-Key header.
`FORBIDDEN`	403	Your API key is valid but you don't have permission to perform this action.
`FEATURE_DISABLED`	403	The requested feature is not enabled for your organization. Contact support to enable it.
`INSUFFICIENT_QUOTA`	403	Your organization has exceeded its usage quota for the current billing period.
`JOB_NOT_FOUND`	404	The requested job ID does not exist or does not belong to your organization.
`JOB_IN_PROGRESS`	409	A job of this type is already in progress. Wait for it to complete before submitting a new one.
`RATE_LIMITED`	429	You've exceeded the rate limit. Back off and retry after a short delay.
`INTERNAL_ERROR`	500	An unexpected error occurred on the server. If this persists, contact support.

Handling Errors

Use the code field for programmatic error handling rather than parsing the message string:

const response = await fetch(
  "https://api.domeagent.com.au/v1/drone-footage/generate",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-API-Key": "dome_live_your_key_here",
    },
    body: JSON.stringify({ address: "123 Collins St, Melbourne VIC 3000" }),
  },
);

if (!response.ok) {
  const { error, meta } = await response.json();

  switch (error.code) {
    case "UNAUTHORIZED":
      // Re-authenticate or check API key
      break;
    case "INSUFFICIENT_QUOTA":
      // Notify user about quota limits
      break;
    case "JOB_IN_PROGRESS":
      // Wait and retry, or poll the existing job
      break;
    case "RATE_LIMITED":
      // Implement exponential backoff
      break;
    case "VALIDATION_ERROR":
      // Fix request parameters based on error.message
      break;
    default:
      console.error(
        `API error [${error.code}]: ${error.message} (request: ${meta.request_id})`,
      );
  }
}

Support

If you encounter persistent INTERNAL_ERROR responses, contact support@domeagent.com.au with the request_id from the error response meta object.