API error format and codes

When a request to the API fails, Omnifox returns a consistent error envelope across every endpoint, so your integration can handle errors programmatically without parsing free-form text.

Error format

{
  "code": 42200,
  "message": "The given data was invalid.",
  "details": {
    "email": ["The email field must be a valid address."]
  }
}

• code: a machine-readable integer, useful for branching logic without depending on the text of message (which can vary with the user's locale).
• message: a human-readable string.
• details: optional object with extra structured info (e.g. per-field validation errors).

Code table

Example: handling a 422 in your integration

const res = await fetch('https://app.omnifox.io/api/v1/contacts', { method: 'POST', ... });
const body = await res.json();

if (!res.ok) {
  if (body.code === 42200) {
    console.log('Validation errors:', body.details);
  } else if (body.code === 42900) {
    console.log('Rate limited, retry later');
  }
}

Tips

• Branch your retry logic on code, not just the HTTP status: a 400/422 shouldn't be retried automatically (it's a client error), while a 429/500 should be, with backoff.
• Always log details in your integration logs — it's the fastest clue for debugging an API rejection.

Troubleshooting

• details comes back null: this happens on generic errors (401, 403, 404, 500) that don't carry extra structured info; message is your only clue.
• I got an HTTP status that isn't in the table: for unmapped statuses, code is computed as status * 100 (e.g. a 418 would return 41800).