Errors

The Braidis API uses standard HTTP status codes and returns structured JSON error responses.

Error Response Format

{
  "success": false,
  "error": {
    "code": "INVALID_PHONE",
    "message": "The phone number provided is not a valid format",
    "field": "phone"
  }
}

HTTP Status Codes

Code	Meaning
200	Success
400	Bad Request — invalid parameters
401	Unauthorized — missing or invalid API key
403	Forbidden — key lacks permission for this endpoint
404	Not Found — no data found for the query
409	Conflict — duplicate request detected
422	Unprocessable — valid format but data can't be resolved
429	Too Many Requests — rate limit exceeded
500	Internal Server Error — something went wrong on our end
503	Service Unavailable — temporary maintenance

Error Codes

Authentication Errors

Code	Description
AUTH_MISSING_KEY	No API key provided in the Authorization header
AUTH_INVALID_KEY	API key is invalid or has been revoked
AUTH_EXPIRED_KEY	API key has expired
AUTH_INSUFFICIENT_SCOPE	Key does not have access to this endpoint

Validation Errors

Code	Description
INVALID_PHONE	Phone number format is invalid
INVALID_ADDRESS	Address could not be parsed
INVALID_NAME	Name fields are missing or empty
MISSING_REQUIRED_FIELD	A required field was not provided

Credit Errors

Code	Description
INSUFFICIENT_CREDITS	Not enough credits remaining (Free tier only)
CREDITS_LIMIT_WARNING	Credits are running low (informational, request still processed)

Data Errors

Code	Description
NO_MATCH	No data found for the provided query
LOW_CONFIDENCE	Match found but below confidence threshold
PARTIAL_MATCH	Only some requested fields could be resolved

System Errors

Code	Description
RATE_LIMIT_EXCEEDED	Too many requests — retry after the specified delay
INTERNAL_ERROR	Unexpected server error — contact support
SERVICE_UNAVAILABLE	Temporary outage — retry shortly

Handling Errors

const response = await fetch("https://api.braidisdata.com/v1/reverse-phone", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ phone: "+15551234567" }),
});

const data = await response.json();

if (!data.success) {
  switch (data.error.code) {
    case "NO_MATCH":
      console.log("No data found for this phone number");
      break;
    case "RATE_LIMIT_EXCEEDED":
      // Retry after the specified delay
      await sleep(data.error.retry_after * 1000);
      break;
    default:
      console.error(`API error: ${data.error.message}`);
  }
}