Errors & limits

The response envelope

Successful responses use one envelope:

{
  "success": true,
  "message": "Get Campaign status successfully",
  "data": { }
}

• GET requests return 200. Create a campaign returns 201.
• schedule, pause, resume and cancel return 200 with data: { id, status }: the campaign ID and its status after the request.
• The recording endpoint /record-url returns its fields at the top level instead of inside data.

Error responses

Always check the HTTP status code first. Anything outside 2xx is an error. Every error from /api/* has the same shape:

{
  "success": false,
  "statusCode": 404,
  "code": "CAMPAIGN_NOT_FOUND",
  "message": "Campaign not found",
  "errors": ["Campaign not found"]
}

Field	Description
success	Always false.
statusCode	The same number as the HTTP status.
code	A fixed, machine-readable code. Use this in your code. See Error codes.
message	A short English sentence you can log or show to an operator. The wording can change, so don’t match on it.
errors	Always an array of strings. For a validation error it lists every problem. For other errors it has one item, the same text as message.

Two errors add one more field:

• RECIPIENT_VALIDATION_FAILED adds errorIndexes (an array of row numbers). See Create a campaign.
• RECORDING_DELETED adds expiredAt (a UTC time string, or null). See Get a call recording.

Write your error handler like this

Treat any non-2xx status as a failure. Branch on code, and log errors. Don’t parse message.

Error codes

HTTP	code	When
400	VALIDATION_FAILED	The body or query is invalid: an unknown field, a missing field, a wrong type, a page that isn’t a whole number of 1 or more, a broken schedule rule, an unknown voice or caller number, or a legacy SIP ID that isn’t yours.
400	INVALID_ID	An ID is not a UUID: an ID in the path, or agentId when you create a campaign.
400	RECIPIENT_VALIDATION_FAILED	Create a campaign: one or more recipients are invalid. Nothing was created.
401	API_KEY_REQUIRED	The X-API-Key header is missing.
401	INVALID_API_KEY	The key is wrong, or it was regenerated.
403	CALLING_NOT_ALLOWED	Your organization is not allowed to make calls. Only start returns this. Contact Gowajee.
404	CAMPAIGN_NOT_FOUND, AGENT_NOT_FOUND, RECIPIENT_NOT_FOUND, CALL_NOT_FOUND, RECORDING_NOT_FOUND	Not found. An ID that belongs to another organization is also “not found”.
409	CAMPAIGN_NAME_TAKEN	Another campaign in your organization already has this name.
409	CAMPAIGN_ALREADY_STARTED	You tried to start a campaign that isn’t DRAFT. A campaign can be started once.
409	INVALID_CAMPAIGN_STATE	Pause, resume or cancel from a status that doesn’t allow it. See State rules.
410	RECORDING_DELETED	The recording was deleted by your data-retention policy, or because its campaign was deleted.
500	INTERNAL_ERROR	Something failed on our side. The message is always Internal server error. Try again later. If it keeps happening, contact Gowajee support with the time and the path.

In rare cases you get a general code for the status instead: FORBIDDEN (403), NOT_FOUND (404) or CONFLICT (409). Handle them like the other codes with the same status.

Each API reference page lists the errors that endpoint can return.

Examples

400

{
  "success": false,
  "statusCode": 400,
  "code": "VALIDATION_FAILED",
  "message": "Validation failed",
  "errors": [
    "property maxConcurrentCalls should not exist",
    "timeWindows.0.time.0.start must be HH:MM (24-hour, two-digit hour)"
  ]
}

When there is more than one problem, message is Validation failed and errors lists each one.

404

{
  "success": false,
  "statusCode": 404,
  "code": "CALL_NOT_FOUND",
  "message": "Call not found",
  "errors": ["Call not found"]
}

409

{
  "success": false,
  "statusCode": 409,
  "code": "INVALID_CAMPAIGN_STATE",
  "message": "Cannot resume a CANCELLED campaign",
  "errors": ["Cannot resume a CANCELLED campaign"]
}

500

{
  "success": false,
  "statusCode": 500,
  "code": "INTERNAL_ERROR",
  "message": "Internal server error",
  "errors": ["Internal server error"]
}

What changed in September 2026

If you built against the older API, check these:

• “Not found” is now always 404. Some endpoints used to return 400 or 500.
• A duplicate campaign name is now 409. It used to be 400.
• Every error has the shape above, with code, and errors is always an array.
• schedule, pause, resume and cancel return 200 with data. They used to return 201 with no data.
• A deleted recording is now 410. It used to be 200 with success: false.
• Start rejects unknown fields, including maxConcurrentCalls, and hours without two digits (9:00). It also rejects a retryInterval under 5 minutes (300000) when retries are on. See Retries.
• A page that isn’t a whole number of 1 or more is now 400. It used to fall back to page 1.

Limits

Limit	Value
Request body size	20 MB. This is roughly 50,000–100,000 recipients per create request, depending on the size of agentParams. A bigger body gets 413. A body that isn’t valid JSON gets 400. Both are rejected before the request reaches the API, so their body is not the envelope above. Rely on the status code.
Page size (/recipients, /calls)	Fixed at 100 items per page.
Rate limit	No fixed per-key limit today. When polling, check each campaign every 1–2 minutes, and never more than once every 30 seconds.
Concurrent calls	One limit for your whole organization (15 by default), set by Gowajee. All running campaigns share it. When Gowajee raises it, only campaigns created after the change can use the higher limit.