Getting Started

Error Handling

How errors are returned by the SmartMCA API

The API uses conventional HTTP status codes and returns structured error responses.

Error Response Format

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [
      {
        "field": "fundedAmount",
        "message": "must be a positive number"
      }
    ]
  }
}

HTTP Status Codes

Code	Meaning
200	Success
201	Created
204	No Content (successful delete)
400	Bad Request — Invalid parameters
401	Unauthorized — Invalid or missing API key
403	Forbidden — Insufficient permissions
404	Not Found — Resource doesn’t exist
409	Conflict — Resource already exists
422	Unprocessable Entity — Validation failed
429	Too Many Requests — Rate limited
500	Internal Server Error

Error Codes

Code	Description
UNAUTHORIZED	API key is missing or invalid
FORBIDDEN	Key lacks required scope
IP_NOT_ALLOWED	Request from unauthorized IP
NOT_FOUND	Resource not found
VALIDATION_ERROR	Request body validation failed
RATE_LIMITED	Rate limit exceeded
CONFLICT	Duplicate resource
INTERNAL_ERROR	Server error (contact support)

Handling Errors

const response = await fetch('https://api.smartmca.com/api/public/v1/deals', {
  headers: { Authorization: `Bearer ${apiKey}` },
});

if (!response.ok) {
  const { error } = await response.json();

  switch (error.code) {
    case 'RATE_LIMITED':
      const retryAfter = response.headers.get('Retry-After');
      await sleep(Number(retryAfter) * 1000);
      // Retry the request
      break;
    case 'UNAUTHORIZED':
      // Check your API key
      break;
    default:
      console.error(`API Error: ${error.code} - ${error.message}`);
  }
}