Error Handling

The Adsroid API returns clear and predictable error responses to help you diagnose and fix issues quickly.
All errors follow the same JSON structure and include a machine-readable error code, a human-readable message, and an HTTP-style status code.

Error responses never consume credits.

Error Format

Every error from the Adsroid API follows this consistent schema:

{
  "error": "invalid_api_key",
  "message": "Your API key is invalid.",
  "status": 401
}

Fields

Field	Type	Description
error	string	A stable error code you can programmatically detect.
message	string	A descriptive explanation of the error.
status	number	HTTP-like error code (e.g. 400, 401, 403, 429, 500).

Common Error Codes

Authentication Errors

invalid_api_key

Your API key is missing, invalid, or disabled.

{
  "error": "invalid_api_key",
  "message": "Your API key is invalid.",
  "status": 401
}

missing_authorization_header

The Authorization header was not provided.

{
  "error": "missing_authorization_header",
  "message": "The Authorization header is required.",
  "status": 401
}

organisation_not_found

The organisation_id does not exist or does not belong to the API key.

{
  "error": "organisation_not_found",
  "message": "The organisation does not exist or is not linked to the API key.",
  "status": 403
}

project_not_found

The project_id provided does not exist or is not linked to the organisation.

{
  "error": "project_not_found",
  "message": "The project does not exist or is not part of this organisation.",
  "status": 400
}

Request Errors

invalid_request_body

The JSON body is missing required fields or formatted incorrectly.

{
  "error": "invalid_request_body",
  "message": "The request body is invalid or incomplete.",
  "status": 400
}

missing_fields

One or more required fields are missing.

{
  "error": "missing_fields",
  "message": "Fields 'organisation_id', 'project_id', and 'message' are required.",
  "status": 400
}

unsupported_content_type

The request must be JSON.

{
  "error": "unsupported_content_type",
  "message": "Content-Type must be application/json.",
  "status": 415
}

Billing & Credits

insufficient_credits

The organisation does not have enough API credits to process the request.

{
  "error": "insufficient_credits",
  "message": "You do not have enough credits to complete this request.",
  "status": 402
}

System Errors

internal_error

A generic unexpected error occurred.
This is rare and usually temporary.

{
  "error": "internal_error",
  "message": "An unexpected error occurred. Please try again.",
  "status": 500
}