Errors - Torpedo

Error format

All errors return a JSON body with an errors array:

{
  "errors": [
    {
      "message": "Domain not verified",
      "field": "from"
    }
  ]
}

The field property is only present for validation errors and indicates which request field caused the problem.

HTTP status codes

Code	Meaning	When it happens
`200`	OK	Successful read or update
`201`	Created	Resource created
`202`	Accepted	Email, SMS or verification code queued (async operation)
`400`	Bad Request	Validation error — check the `errors` array
`401`	Unauthorized	Missing or invalid `X-API-Key`
`402`	Payment Required	Plan quota exceeded, or not enough SMS credits or WhatsApp balance
`404`	Not Found	Resource doesn’t exist or belongs to another workspace
`409`	Conflict	Duplicate resource (e.g. domain already registered, or a verification already pending)
`410`	Gone	The verification already ended (approved, expired, canceled or too many wrong codes)
`422`	Unprocessable Entity	Business logic error — domain not verified, recipient suppressed, domain scope mismatch
`429`	Too Many Requests	Rate limit exceeded — back off and retry
`500`	Internal Server Error	Something went wrong on our side
`503`	Service Unavailable	A channel isn’t available right now (for example, WhatsApp sending)

Rate limiting

Authenticated API requests are rate-limited per workspace: up to 50 requests in a one-second burst and 1,000 requests per minute. If you exceed either limit you’ll receive a 429 response with a Retry-After header indicating when you can retry.

HTTP/1.1 429 Too Many Requests
Retry-After: 30

Handling errors

Node.js

const res = await fetch('https://api.torpedo.co.mz/api/v1/emails', {
  method: 'POST',
  headers: { 'X-API-Key': process.env.TORPEDO_API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    from: 'hello@myapp.com',
    to: '...',
    subject: '...',
    html: '...',
    text: '...',
  }),
})

if (!res.ok) {
  const { errors } = await res.json()
  console.error(errors[0].message)
}