Errors

The Replicer API uses standard HTTP status codes and returns consistent JSON error responses.

Error response format

{
  "error": {
    "code": "validation_error",
    "message": "agentId, toNumber, and fromNumber are required",
    "details": null
  },
  "requestId": "req-abc123"
}

Field	Type	Description
error.code	string	Machine-readable error code
error.message	string	Human-readable description
error.details	object | null	Additional context (when available)
requestId	string	Unique identifier for debugging

Error codes

Client errors (4xx)

HTTP Status	Code	Description
400	bad_request	Malformed JSON or invalid request body
400	validation_error	Missing or invalid field values
401	unauthorized	Missing or invalid API key
403	forbidden	API key is inactive or expired
403	insufficient_scope	API key doesn't have the required scope
404	not_found	Resource doesn't exist or doesn't belong to your organization
429	rate_limit_exceeded	Too many requests — check Retry-After header

Server errors (5xx)

HTTP Status	Code	Description
500	internal_error	Something went wrong on our end
503	not_implemented	Endpoint is planned but not yet available

Handling errors

const response = await fetch('https://api.replicer.ai/v1/calls', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer rpl_live_your_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ agentId, toNumber, fromNumber }),
})

if (!response.ok) {
  const { error, requestId } = await response.json()
  
  switch (error.code) {
    case 'rate_limit_exceeded':
      const retryAfter = response.headers.get('Retry-After')
      // Wait and retry
      break
    case 'unauthorized':
      // Check your API key
      break
    case 'validation_error':
      // Fix the request body
      console.error(error.message)
      break
    default:
      // Log requestId for support
      console.error(`Error ${error.code}: ${error.message} (${requestId})`)
  }
}

Request IDs

Every response includes a requestId field. When contacting support about an error, include this ID to help us investigate.